HPC 


Run-Time Library Reference 
Manual for OpenVMS Systems 


Order Number: BA554—90002 


July 2006 


This manual describes the functions and macros in the HP C Run-Time 
Library for OpenVMS systems. 


Revision/Update Information: This manual supersedes the HP C 
Run-Time Library Reference Manual 
for OpenVMS Systems, Order Number 
AA-RSMUC-TE, Version 8.2 


Software Version: OpenVMS [64 8.3 
OpenVMS Alpha 8.3 


Hewlett-Packard Company 
Palo Alto, California 


© Copyright 2006 Hewlett-Packard Development Company, L.P. 


Confidential computer software. Valid license from HP required for possession, use or copying. 
Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software 
Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government 
under vendor’s standard commercial license. 


The information contained herein is subject to change without notice. The only warranties for HP 
products and services are set forth in the express warranty statements accompanying such products 
and services. Nothing herein should be construed as constituting an additional warranty. HP shall 
not be liable for technical or editorial errors or omissions contained herein. 


UNIX is a registered trademark of The Open Group. 
X/Open is a registered trademark of X/Open Company Ltd. in the UK and other countries. 


Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries 
in the United States and other countries. 


Printed in the US 
ZK5763 


The HP OpenVMS documentation set is available on CD-ROM. 


This document was prepared using VAX DOCUMENT Version 2.1. 


Portions of the HP C Run-Time Library have been implemented using source copyrighted by the 
University of California, Berkley and its contributors. 


Copyright (c) 1981 Regents of the University of California. 
All rights reserved. 


Redistribution and use in source and binary forms, with or without modification, are permitted 
provided that the following conditions are met: 


1. Redistributions of source code must retain the above copyright notice, this list of conditions 
and the following disclaimer. 


2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions 
and the following disclaimer in the documentation and/or other materials provided with the 
distribution. 


3. All advertising materials mentioning features or use of this software must display the following 
acknowledgement: This product includes software developed by the University of California, 
Berkeley and its contributors. 


4. Neither the name of the University nor the names of its contributors may be used to endorse 
or promote products derived from this software without specific prior written permission. 


THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS” AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS 
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE. 


Contents 


PCTACC sos ssn ane eee pea es ts se XXV 


1 Introduction 


1.1 Using the HP C Run-Time Library ......... 0.0.0.0... cece eee 1-2 
1.2 RTL Linking Options on Alpha and I64 Systems (Alpha, 16g ............ 1-3 
1.2.1 Linking with the Shareable Image....................00 0 eee ee 1-3 
1.2.2 Linking with the Object Libraries (Alpha only)... oe 1-4 
1.2.3 Exam ples: fi0'3 a6 wha bs © Bae eh eS hee ede Cede Eee da ee 1-5 
1.3 RTL Linking Options on VAX Systems (VAX only) 6. ee 1-6 
1.3.1 Linking with the HPC RTL..... 1... es 1-7 
1.3.1.1 Linking with the HP C RTL Shareable Images ............... 1-7 
1.3.1.2 Linking with or Providing Your Own Shareable Images ........ 1-8 
1.3.1.3 Linking with the HP C RTL Object Libraries ................ 1-8 
1.3.1.4 Linking with the HP C RTL Object Libraries /NOSYSSHR...... 1-9 
1.3.2 Resolving Link-Time Conflicts with Multiple C RTLs ............. 1-9 
1.3.2.1 Using VAXCILOCLOPY . accucssexs nevi etkacdee aks sauiack 1-10 
1.3.2.2 Using VAXC$EMPTY.EXE ...... 0.0.0.0... cee eee 1-11 
1.3.2.3 Using DECCOEMPT YUE <<.c4.0% ee kbeach sukeseae bvnetaees 1-12 
1.3.3 Linking Examples for HP C or HP C++ Code Only ............... 1-12 
1.3.4 Linking Examples for VAX C and HP C Code Combined ........... 1-13 
1.3.5 Linking with the VAX C RTL/NOSYSSHR .................005. 1-14 
1.4 HP C RTL Function Prototypes and Syntax........... 0.00.00 eee 1-14 
1.4.1 Function Prototypes ...... 0.0.0... eee ene eee nee 1-14 
1.4.2 Syntax Conventions for Function Prototypes ................000. 1-15 
1.4.3 UNIX Style File Specifications ...... 0.0.0.0... 00. 1-15 
1.4.4 Extended File Specifications ........ 0.0.0... cee ee ees 1-18 
1.4.5 Symbolic Links and POSIX Pathnames ..................02005. 1-18 
1.5 Feature-Test Macros for Header-File Control.................0.005. 1-18 
1.5.1 Standards Macros ......4 chee. eo chhacead ceded eee eiaceeads 1-19 
1.5.2 Selecting a Standard ...... 0... 0. eens 1-19 
1.5.3 Interactions with the (STANDARD Qualifier .................... 1-21 
1.5.4 Multiple-Version-Support Macro ....... 0.0... cece eee nes 1-23 
1.5.5 Compatibility Modes ......... 0... cee eens 1-24 
1.5.6 Curses and Socket Compatibility Macros............. 0.00000 ee 1-25 
1.5.7 2-Gigabyte File Size Macro ........ 0.0... cece eee ee 1-26 
1.5.8 32-Bit UID and GID Macro (Alpha, 164) 1. 1-26 
1.5.9 Standard-Compliant stat Structure (Alpha, 164) 2.6... 6 eee 1-26 
1.5.10 Using Legacy _toupper and _tolower Behavior (Alpha, 164) ........... 1-27 
1.5.11 Using Faster, Inlined Put and Get Functions (Alpha, 164 ............ 1-27 
1.5.12 POSIX Style exit (Alpha, 164) 0. eee 1-27 
1.6 Enabling C RTL Features Using Feature Logical Names ............. 1-28 
1.7 32-Bit UIDs/GIDs and POSIX Style Identifiers ...................04. 1-44 
1.8 Input and Output on OpenVMS Systems............ 0.0.0 eee eee 1-44 


1.8.1 RMS Record and File Formats............... 0000. e eee ee ee 1-46 


1.8.2 Access to RMS Files... 0... 0... eee eee 1-48 
1.8.2.1 Accessing RMS Files in Stream Mode ................22005- 1-48 
1.8.2.2 Accessing RMS Record Files in Record Mode................. 1-48 
1.8.2.2.1 Accessing Variable-Length or VFC Record Files in Record 

Mode v4 cidae saeieke eGeas Chi eb etd hase er teehee vanes 1-51 
1.8.2.2.2 Accessing Fixed-Length Record Files in Record Mode ....... 1-51 
1.8.2.3 Example—Difference Between Stream Mode and Record Mode... 1-52 
1.9 Specific Portability Concerns ........... 0.0 ee eens 1-53 
1.9.1 REGntraNnCy so. sss 2 BSS et nee whe SS as oe Ew eS Se ees 1-55 
1.9.2 Multithread Restrictions ........ 0.0.0... cece eee eee 1-58 
1.10  64-Bit Pointer Support (Alpha, 164) 2.6... ce ee eee 1-58 
1.10.1 Using the HP C Run-Time Library ................ 000000 1-59 
1.10.2 Obtaining 64-Bit Pointers to Memory .................00 ee eee 1-59 
1.10.3 HP C Header Files... 0.0... eee ene 1-60 
1.10.4 Functions Affected .... 0.0... 0... enn eens 1-60 
1.10.4.1 No Pointer-Size Impact ....... 0.0.0. 1-61 
1.10.4.2 Functions Accepting Both Pointer Sizes.................0005 1-61 
1.10.4.3 Functions with Two Implementations ..................000. 1-61 
1.10.4.4 Functions Requiring Explicit use of 64-Bit Structures.......... 1-63 
1.10.4.5 Functions Restricted to 32-Bit Pointers .................004. 1-65 
1.10.5 Reading Header Files... 1.2... 0.0... cece eens 1-65 


2 Understanding Input and Output 


2.1 Using RMS from RTL Routines ......... 0... 000 ees 2-4 
2.2 UNIX V/O and Standard VO... 2... eee 2-5 
2.3 Wide-Character Versus Byte I/O Functions ................00000 00s 2-6 
2.4 Conversion Specifications... 0... 0... eee eens 2-7 
2.4.1 Converting Input Information ............ 20.0000 eee eee eee 2-7 
2.4.2 Converting Output Information ............ 0.000. cee ees 2-13 
2.5 Termimal VO 22%. cee we iow Bie et in eh ee BP Ri OR a ah Be eed eae hee 2-19 
2.6 Program Examples::..0s.c05 oh¢.e0028gne oo eae SS ea Ree eh era Rohe ges 2-20 


3 Character, String, and Argument-List Functions 


3.1 Character-Classification Functions. ........0.. 0.0.0 cece eee eee eee 3-4 
3.2 Character-Conversion Functions .......... 0.0.0. c eee cnet eens 3-7 
3.3 String and Argument-List Functions ...........0.. 0000 cc eee eee 3-9 
3.4 Program Examples «6 s063.¢ sac nha oa ae ods baa ae aw eda Hays 4 3-10 


4 Error and Signal Handling 


vi 


4.1 Error Handling? < cceid ceaeee eed d aE OR oa a Ee sO eE REE OR ERM EE OS 4-2 
4.2 Slotial Handling sce. sadansé ae ewes ea ea eee Oe eRe oe ee ae 4-5 
4.2.1 OpenVMS Versus UNIX Terminology.................000 ee eee 4-5 
4.2.2 UNIX Signals and the HPC RTL ................... 0.000005. 4-6 
4.2.3 Signal-Handling Concepts ......... 0.0... eee ees 4-8 
4.2.4 Signal ACHONS 603 eisesce% sated aia Wye be Es ¥ ake anes wine ha wh G A 4-8 
4.2.5 Signal Handling and OpenVMS Exception Handling.............. 4-9 
4.3 Program Example ....... 0.0... ccc ee een eens 4-14 


5 Subprocess Functions 


Implementing Child Processes in HPC ......... 2.0... 0.0 eee 
The exec Functions .......... 2... 

exec Processing ...... 0... cece eee eee eee neee 

exec Error Conditions .......... 0.00. ees 
Synchronizing Processes ...... 0.0... ce eee ees 
Interprocess Communication .......... 0000. cee ee ees 
Program Examples ss.4 o¢.54 04 oye bea deed ee boe aidivde bee anaes 


6 Curses Screen Management Functions and Macros 


6.1 


Using the BSD-Based Curses Package (Alpha only) 2... 0. 0c es 
Curses Overview ......0. 0. ccc cee eee nee nent ene 
Curses Terminology: . ¢ cise beg ea ae ew Bais Waa Ha el eae 

Predefined Windows (stdser and curscr).............0 00 eee eee 

User-Defined Windows ......... 0... ccc ee eee tenes 
Getting Started with Curses ........ 0.0... eee ens 
Predefined Variables and Constants............ 00.00 c eee eee eae 
Cursor MOVEMEHE } 23.36.66 seid Dae Bese ORE ea Ee Re OE CMS ee hE WR 
Program. Example: oo c.c0¢0h be ed oak i hb ewe ES RE eae CREE CORE ES 


7 Math Functions 


7.1 
7.2 
7.3 
7.4 


Math Function Variants—float, long double (Alpha, 164)... 2.2.0.0. eee 
Hrror IDGteCtiON: ici... ay Seaceies G4 5b howls Sb Os feretels Hy OS eos we ee ae 
The <fp:h> Header Pile: « ¢ icici sccekue bate cee ee beaea be bia cete eet 
Bxaiiples ¢, iapeG haha edie ee Gdn ee aE ded g hada ee ee 


8 Memory Allocation Functions 


8.1 


Program Example: ..cccxes haa ciee dee ecees bee heed eeeeaw eas 


9 System Functions 


10 Developing International Software 


10.1 
10.1.1 
10.1.2 
10.2 
10.3 
10.4 
10.5 
10.6 
10.7 
10.7.1 
10.7.2 
10.7.3 
10.8 
10.8.1 
10.8.2 
10.8.3 
10.8.4 


Internationalization Support ....... 0.0.0... ee eee 
Tristallation: s¢ 6 a0. 4% awe heek che agh Dare he eee ad wy ee g bode 
Unicode Support: 2x2 scanaceadeerasdadews ata dece gata aacusas 

Features of International Software .......... 0.0... ee ee 

Developing International Software Using HPC..................... 

WiOCAlES: 00. is eee ees A ere he Se BE OSE a ee ee Bete ee 

Using the setlocale Function to Set Up an International Environment ... 

Using Message Catalogs ... 0... 0... ccc eee ees 

Handling Different Character Sets ........... 0.0. ee 
Charmap Piles. .65.6 he ekd eee eee hee divead ae Oaee Ree dino ks 
Converter Functions... .i0 cued bed eee ae GOW eee eee ee eee ee 
Using Codeset Converter Files... 0... 0.0.0.0... nee 

Handling Culture-Specific Information ................ 0000 eee eee 
Extracting Cultural Information From a Locale.................. 
Date and Time Formatting Functions ............... 0.000. e eee 
Monetary Formatting Function ........... 0.0.00 eee ee eee ee 
Numeric: Formattin® -04.,.4.2.6 vis GG. b. va Paws As eae eee ae 


10-1 
10-1 
10-1 
10-2 
10-3 
10-3 
10-4 
10-5 
10-6 
10-6 
10-6 
10-6 
10-8 
10-8 
10-8 
10-9 
10-9 


vii 


11 


10.9 Functions for Handling Wide Characters ................00 0 eee eee 
10.9.1 Character Classification Functions .......... 0.00.0 ee eee nee 
10.9.2 Case Conversion Functions ........ 0.0.0.0 cece eee nes 
10.9.3 Functions for Input and Output of Wide Characters .............. 
10.9.4 Functions for Converting Multibyte and Wide Characters.......... 
10.9.5 Functions for Manipulating Wide-Character Strings and Arrays..... 
10.10 Collating Functions ....... 0.0.0... 0 cee eee 


Date/Time Functions 


11.1. Date/Time Support Models.......... 0.0.0... eee 
11.2 Overview of Date/Time Functions ........ 0.0.0.0... cece eee 
11.8. HPC RTL Date/Time Computations—UTC and Local Time ........... 
11.4 Time-Zone Conversion Rule Files......... 0... 00. cece eee 
11.5 Sample Date/Time Scenario ........... 0.0... eee eee 


12 Symbolic Links and POSIX Pathname Support 


viii 


12.1 POSIX Pathnames and Filenames ............ 0.00000 ee 
12.1.1 POSIX Pathname Interpretation .......... 0.0.0.0 cece eee eee 
12.1.1.1 The POSIX Root Directory .............. 00. e eee ee eee 
12.1.1.2 Symbolic Links ¢ o's o sd.i4 goo eee phe Paes CE META wR SOR OEN 
12.1.1.3 Mount Points: 6 oy dco dee eh ee OPES EEE OES eRe eS EE ER ew S 
12.1.1.4 Reserved Filenames. and ......... 0.2.0... ce eee eee eee 
12.1.1.5 Character Special Files ... 0.0... 20.0... cee ee eee 
12.1.2 Using POSIX Pathnames with OpenVMS Interfaces .............. 
12.1.2.1 Special Considerations with POSIX Filenames ............... 
12.1.2.2 Special Considerations with OpenVMS Filenames............. 
12.2 Using Symbolic Links ........... 0.0... eee 


12.2.1 Creating and Using Symbolic Links with DCL .................. 
12.2.2 Using Symbolic Links through GNV POSIX and DCL Commands.... 
12:3" 2C RYU Support oc ox, se 6 6d eee SRS ata lg WR ele Sie ORS ERR Rade dean’ ’s 
12.3.1 DECC$POSIX_COMPLIANT_PATHNAMES Feature Logical ....... 
12.3.2 decc$to_vms, decc$from_vms, and decc$translate_vms ............ 
12.3.3 Symbolic Link Functions .......... 0.0.00 cece eens 
12.3.4 Modifications to Existing Functions ................0. 000 eee 


12.3.5 Non POSIX-Compliant Behavior ........... 0.0.00 eee eee eens 
12.3.5.1 Multiple Versions of Files....... 0.0... 0.00. 
12.3.5.2 Ambiguous Filenames .......... 0.0.00 e eee eee eens 
12.3.5.3 POSIX Security Behavior for File Deletion .................. 


12.4 RMS Interface 24 cies ec cce eee e babe cee e cab ee eee eee eee e eee OES 
12.4.1 RMS Input/Output of POSIX Pathnames....................045 
12.4.2 Application Control of RMS Symbolic Link Processing ............ 
12.5 Defining the POSIX Root ......... 20.0... eee 
12.5.1 Suggested Placement of the POSIX Root ....................0.. 
12.5.2 The SET ROOT Command............. 0.0.0 ee eee 
12.5.3 The SHOW ROOT Command.............. 00.0 e eee eens 


12.6 Current Working Directory ......... 0.0... eee 
12.7 Establishing Mount Points.......... 0.0... 00 ee eee 
12:8: NES. c cde ees aw 2654 Gna e8e 4 Abe aOES Oa se OHSAS RE CTSGS ERE EER 
12:9. WNC Vire oe seers bs es wee ea oe es ws Oe es eae 
1210 JUGNV iV occide ea wckda Ge laduniabebatieadebaat eiee bhatecieba wees 


U2: ~RESEMICHIONS «5 & teem ce: Geena ets 2 Soest hee hoes: Sane Gi eceera Rance hes 


Reference Section 


AGAL Alpha I6d) koa chad hee db been Rowe RE ROR be Ree ba Read REF-3 
ADOLE eed ae nd ted hee ch emid be aie edhe oh eae bdo ae tod habe at ams REF-5 
ADS 2 cad adeeb a Riad ceae Adee eRe Raed Cee Lada ens Ada maetee as REF-6 
ACCOR Sse Sse ee aes hehe ve cise One oe wd Sane hoes Reet aed oe eee ees REF-7 
ACOS snc. Bed dbo RARE Ad ORE SaRA EREDAR ERG A ORS ORES ARE RRS REF-9 
ACOSH AlphasI6D  sodeeeee bso aoae gee Gia murs eh oA Ow Awe Steed area sees REF-10 
[IAMCH. 4 oc ae dnc sen Gee eB G Bek he ed Oe aA ee oe aes bewe ed REF-11 
[WL AUAS GH a sc seive ae B.S anal leeds cee eial agi ah bw. ahha a eR AV ane Grae le need @ aA REF-12 
ALAN oat So wd Re Ae heehee wd Sab PEARE bade SOR Ee Dh bee eee eee REF-13 
ASCHIME, ASCTIME Tf os oh he Sh healed Gl dw os SE low eOEEE Rl eee sd REF-14 
ASIN seiko adea done dda BA aaa he ee Re hs BAe se a AS Oe ee REF-16 
asinh (Alpha, 164) 24% ic sedaee cde e eee ba eed eee ban eR Ee Eee eee ee REF-17 
ASSOEU fc, ¢ ogee Tete eS Ries eras by eats Gis aba asa Up ee eee be aoe REF-18 
Ata vice aacei ae bene bee eee Gh iaG bead area patei deeend bias &s REF-19 
RAND 2595 2s ap hes nes cayles ay gatas Wry ras Be Mn ay tsp Od nae e ape Og eed ea: ay an ae a REF-20 
atanh: (Alpha, 164) <s0caned aw cad eee eben PA eee be eee ewe eats REF-21 
LOKI Gjovisc 4 aig ettity said us Spivak bya Shar asiele Gh Babee aod 4 Ee etd a de > Sales es REF-22 
ALOL es ces halen Ged ie hes ee bad end ba eh eee badlendeedeceeaded REF-23 
ALO], ACOD gi. cease Gy ose els to Ae WE Ae. ea Soh wh awe AE 8 aN eon whe eae aan satleine ead is REF-24 
atoq, atoll (Alpha, 164) 6. eee eee eee REF-25 
DASENAINE «6k edod-dsoe. ose dak @ sera Mr Bh NGn: Shen's OG A Dekel Pw AN Sdea in Ooh aes REF-26 
BCMP: 2s kc adee hace aa aoe ks OR Eee Ra ee aaee se bheadue ha wseeaunes de REF-27 
DCOpY 2%2 ows itne Gaeta te wwe ahaa dare cee eww seein o Geet he REF-28 
DOXo 6 6a bub hae heed de BR wd Dacerw ee Made ae & daha aan abe Rube 6 REF-29 
DEK 0 sce: since te, oa ee a Hw aha, 0 see, a,b Wah bea ane DEY hae, o Soe bhe heie ee REF-30 
bsearchs o.0 2 sa chk sedan dce aki a hae ed aha deo hade mache endaweeekes REF-31 
btOWG! 2scte4 eek Meee tate eee othe 4 ended hese seth weds ee ge ee REF-33 
IDZCTO! 20-8 <b edited nse aD 4 oy SR DO saed <b ese nad aes eenews REF-34 
CADS. 2 itech edea deed wked eee bakeceeei wee ieGe badendedt cadences REF-35 
CACOS Alpha: I64) sis, bo vais as deds 228 oda SRS eG Re ee ees HA ee es REF-36 
cacosh (Alpha; 164) 4 ciacdas cede eee be ede Od eba baa edadeereedade es REF-37 
CANN OG: ees es de dpea aces Gea aes bo Paes ane wap oe ee oe ew REF-38 
Care (Alpha, 164 fibie8 268 Goa SOR ELERERER EOL SR EOGE ELS baad REF-39 
CASIN, (Alpha; 164): ois ay a ta aw Ra ea Bie Re eae eR a ae ee a ye Se REF-—40 
Casinh (Alpha: 164) ia heehee en ae eee eh eee Ce aees eke ee ea here meee REF-41 
Catan. (Alpha: 162) kt dewg bowie een a beh bees a Oe PH aw ne Ses REF—42 
CAtAN A AAG TED) xe cect tect RBs a Race ie hnadodd lec Raed Gi Buck we Rn el Glee Recess REF-43 
CALCIOSES 92.55 asain heh ba, Wee Ie add eis gS, wher EAS SO MARA oe as REF-—44 
CGESTLESX =] HE rae ro ee a eee REF-45 
CALOP EI send eo hie ails tated id ook Send a Sw whe Yee ek enka anes eed ahh Sade eed dod gene REF-48 
Chrt:ipna; 164) oc oak. bh alae eae A wR Ge alae SR ee A ae eR REF-51 
CCOS (Alpha, 169) noes Sas Sie Su Be EOLA Da CRE RRAM EWS CE Re ee eee REF-52 
CCOSD: Alpha; 160). ca ce oa bata cdda car bas bad ncddaceadbaa Sbadaws REF-53 
COLD oe) en bet, waht Sees 9 dos RRL den, Dead Paw ew AML Were wi eeew a bw ae oder REF—54 
COXD MAING 162)” scataricteteay ats cilets oon a ae ero ay BE a eae ae laey ae Re REF-55 


CAG sid Othe ee edd comiban Shek a bdhadem cede Sher aeeb hd aaa baa Gds REF-57 
CHIMOd. be acewne eee dan bo aede eglh oaacdd gale egw eb geht bw aed REF-58 
CHOW Dis cece hod ck and he Adee RA eee OAR dR dhe eda ds REF-59 
CIMAL (Alpha, 164) vie dak baw eee RRS RERN OER SEE ES CORSE EER OER EES REF-60 
PWICIGEI 5.526 a nig a bp atsten ard asp atatee od 4b attuned any eee a eet ead & aE REF-61 
CIGATETT <i ci ec eed ee bie eee Leen bn bh PRE HE SEER eA PEER REF-62 
clearerr_unlocked (Alpha, 164) 2... oc ee eee eee eee REF-63 
Cléarok 3 0.iis eevee dees be kode wedded de de kedane Pewee Ee eee es REF-64 
CLOCK as 5 shidcas ernsrd cant) Sag hein aa as araie epee etad ae oe aais oy Ge oie ey ee REF-65 
clock_getres (Alpha, 164... nent e eae REF-—66 
clock_gettime (Alpha, 164... eee eee e eens REF-67 
clock_settime (Alpha, 164) 6. ene ees REF-68 
ClOS AID RGR IGA) sence, Se aya teach Hal ORS UE hee OR OER UR Re Ee ee REF-70 
COSC nce ceed kk ad che Ade Se eka ea eee aha Dea ode de eae es REF-71 
CLOSEOIE oi6 2516. 025 oeeGia ee Ee and wale OU ae Re Ga Ral oR Re anes REF-72 
[Wiclrattr 64.6 c00 d hed eae Odea aca nd deh aedtadara bard dadwedeads REF-—74 
EWICITtOBO: 6 oink dw ace eee ae bak ee a heats Sadie eh ek baie boar ane tate ea bes REF-75 
wielrtoeol, ac. dcacnd da cea cen a dda webs Bana ee ed dead ha eae es REF-76 
CONST await Be OO SRR Ew Ee owed AD aka ae he oe oa a Gue s REF-77 
CON) Alpha; 169 2.6 hho ake OL ER AER Cao MERE DEER REE EAS MRREY EE REF-79 
COPYSIST (Alpha, I6): wae h dwn be ale ede wk bee dD alk wie, Ware tlw ban REF-80 
GOS. ictey's apd sates suse ay 0a, Re sa ee ay ae wees oy Ree ea BE Ree a, eRe REF-81 
COSH: sa 4.0 886 bab Cee Cee ew ene ee boeken Phew be eee Gee ees REF-82 
COs re a Batetere td 4b bao ae kin Bae ek ee ee eae by Balad cee BO REF-83 
CDOW Alpha 160) 6.4.4. 86068444 E83 EE LER EAS SELES AS EE LE eee EL eee REF-84 
CDLO) AlbRG: 16D) va eG 8 obs soso ee hes, BE ha BS a EER As RSS REF-85 
Creal (Alpha, 164). cvawdvdwecteedane eve ved ewadeedad een ededeeteeds REF-86 
GEO css oats, aos uh Ga pe eed em Be ara ee seed ee BE red ee SU ee we Oe REF-87 
[nolCrMOde? sic 420Ge i debe e deeded eRe eG bese bade R eh de beeen REF-93 
CLYDE deen Oh ee eee ee Pe Se Oe See Lae eee Whe ee eb Dates REF-—94 
CSI WAIphG, 16) tink d.d08 & wack Rid PR deed Mare @ Rea wee RAE Ge eed Ses REF-95 
COIN ATDNGS TOD) 0.0 we see rb obeng wie eee, ead een BOL Pee, & Bees} wae REF—-96 
CSOT (Alpha; 164): ie wens cb dos ed alee wk a he Oe Mad! Eee Se Ba ed ead ase REF-97 
CLAIN Alpha: 164) <tevesergfstiece tt, ac eiw a's edhe aie ew, wai a ts WOR a a eee neers REF-98 
ctanh (Alpha; 164) onc eked a hee dba hehe dea deeb eeeadedncd ence REF-99 
CEGETIN G25, ese ca dig whee Dae gah aod Hoe ah ela ew qe pooh eae hw abe tated ew aes REF-100 
Chime, ChIME Ts bogs he A ee ARRAS ERA DEEDS CRRA EERE SS REF-101 
CUSOLIG sg 8 eid ee whi Be ie Be ee ee De eae i Rae Wee ew REF-103 
DECC$CRTL_INIT .......... 0.0 teens REF—104 
decc$feature_get. 0... ccc eee eee teen teens REF—105 
decc$feature_get_index . 0.0.0... ccc cece ees REF—106 
decc$feature_get_nMaMe ....... 0... eee eens REF—-107 
decc$feature_get_value.. 6.6... teen ees REF—108 
decc$feature_ set... 0... ee eee ee eee eee e eee e nee eens REF—109 
decc$feature_set_value..... 0.0... cee cence eee een nes REF—110 


decc$feature_show ...... 0.0... ccc ee ee eee e eens REF—111 


decc$feature_show_all ... 0.0.0.0... eee eee ee REF-112 


decc$fix time .. 0.2.0... ee ee eee ene e ene ee nee en nes REF-113 
dece$from:cVMSse6cds, v. gs0e bee hie ave ek aes HR eee Bw are Pa oH es REF—114 
dece$match wild ....... 0.0... eee eee tenet eens REF—116 
decc$record_read ....... 0... cece cee eee eee nee nee ennes REF—117 
decc$record write... 0.0... eee ee eee cnet cnet eens REF-118 
decc$set_child_default_dir (Alpha, 164) 0... cee ees REF-119 
decc$set_child_standard_streams............... cece eee eee ennes REF-120 
decc$set_reentrancy ... 0.0... eet eee ees REF-124 
GOCCHLO Vimiseate tk glnataseuts Shida Gade dng om vee SS a Had Gre ool anaes meaee REF-126 
decc$translate_VMS 1... 0.0.0... eee eens REF-128 
decc$validate_wchar.......... 0... eee eee eee eee e eee eens REF—130 
decc$write_eof_to_mbx.. 0.6... eee enn nes REF-131 
[WIIPIC a x ecented och gees dé cea knee eteee ae CARERS Es hohe eas REF-134 
delete wks owe ets Swe Be ewe SB ea wee aa Be Ow RE De a Bae ee REF-135 
[wideletelit::.s..ccakeau ceed beddace ahead ioa eed daceaked deacrea as REF-136 
GelWit sym owe ttbantwaneeeae wah teed wake dae wy aeiden ob wade REF-137 
IAAI S35, aay tox aed aye a a whe GWA ee Ro we ee SY we ee a eee REF-138 
GiPMMaMe .2sk ech w deen atewe oe bade whee de Tee Meese ewe eed eee Aes REF-139 
LD eins ke yen ved cas) Susie ee rm) Sees ee ae & Gs ye ees be REF-141 
dIClOSe-24 2h eteee eel weed ee chee ee ei Pe ete ec chemin eeei ven saees REF-142 
LST ONE, severe, eg ay asst ex ay tee ain a cecee, sa wy atc too Aye ran, eesre eis ha cs, “ex ayia Nie eto REF-143 
GlOpen: c.ciecccee eee te etaae eee ede deetretead obeee tebe te etade ee REF-144 
GIS YIM oie ok Soh ates hay eres Peo Paes ee ade wad eo ee eee REF-145 
drand4s ci sc2i6eb iad sao h bbe Sede hbewiieteieteiautene enous REF-146 
GuUp;-dup2ic eset bak Seni oe ceed Be eee he eee ae & Sa ars REF-147 
[NOlECHOM io dice aieoa ceed ced dananSbrdtrackeddanacinedat aed wed REF-148 
COVE: ace eae wwe bare bea eae ae SR oa Oa Ode oe dobee bw Rte cies REF-—149 
CNCIY Pls. eta sd. cbde nda meeeGiabhcced dea okee Geka pa cbeecadamer eka REF-151 
Ondgrent. (Alpha, 164). a: hice phe ee a pe wee UR a eee Bee es REF-152 
Cd PWENE gic.c Kee Gade a dead be ed Mode a Rd AOR EMEA AEE Son ese REF-153 
OTA WAT a esse. fe dow a0 ated oh eek oeeesie Sow ale wee ee doh bee Gadiw aOR tote wad ace bes REF-154 
C2) O21 010 Co ea a REF-155 
[WICTASE 220 RA oe ee Ra ew eRe eee Ral ewe SR Bee ewe Be REF-156 
ONE cd ater a aed sty Soest ap ay en oe d Gaye gone ees se Gok gE oe Gs SU REF-157 
OXGC) : tiie ack faded © dod pede bE a ake bok Sed ack Sead Bee Se REF-158 
OCDE 35a, canp ase 0a a Seren Bs ans a “ens ag aaa fap itn gan ig an hs aa ee aa REF-—160 
CX6CIP tuccetecedteet aventeet ec ob ead ePemeee Lede tebe d eves REF-161 
EXECV: thnk d aypaediareed ds Salat 4 © Hatiecns ye ey Ms we aleve 5 eR a REF-162 
CXECVE 6b ciadlea me ha SOG OG Eb aa eee ARR ELE GE dal ee DERE R EE ERO REF-163 
CXECVD! chew ys Paha Ba Ae eee ahs) Mae Ae wae eee ewe ee REF-164 
RDG HO KA G c. ape rect eee At aco dicance Oo eeaute Regeiaa at ates Bd ne Bae Re tend: ee ean tear & REF-165 
EXD ix. ctepayiere ansypp pips Sate a area BeOS ae eee ed ep a eee Sa ee REF-167 
OXP2 Alpha 162) ic eee awe. ae eead eae SRE ces S Ce RE AOR ERED EASE RES REF-—168 
FADS) 2 '6b a eee Re CONGR 2 WEE Ben Se eRe hws eRe we Be REF-169 
{chmod i220 ci cea Obed Ohetebedawes Mead bheaeed gee ghee Shadows REF-170 
FOTO WIN 56.20.50 bee ended ese ve dew ayaa dete bahay bneses id dwanec y veces de we debe eh apeacets REF-171 


xi 


xii 


TCIOSEY jaesseerctn atte wife onlda oe ete wd dy Ss eae Aa te ah Pa eS ek aiSodel ete wipe REF-172 


ft ccd Chew edd camber Ohekacdharemaeae Sheraeeh hd aaabes Xa REF-173 
TOV ics chek were. fe eiay te Pesan op Ae Seer ie oh eee Wa Ore eb we Reese boat REF-179 
fdim:(Aipha; 164) ck ed ce nde ede wh RA eee RATER RA ae eas REF-181 
fdOPEN «5 eee ba vde Eh Oh eRe ee EEO ER ER See dete need de Fh ete eee REF-182 
TOOE 6 is. 5 Miptene ht oan aie yy Ma oe eaten ed any Oe Ge eet eros > we REF-183 
feof_unlocked (Alpha, 164 6... eee eee eee REF-184 
TOLTOR 3. hi0 Gan fe ha wn ha BA See he Oe ee hae See he ee a REF-185 
ferror_unlocked (Alpha, 164)... 0. cee eee eae REF—186 
HHS, agers Gps Peed owe eos Gees Gb eae bee eee aes REF—187 
iss eee ae a ese cs nS ee sees Sse i Se ees Ss a eee eee REF—188 
POOL site op dicta as ok poten as eg eee say aa tates oy ee eee pees eh eee a eye ayes REF-189 
fgetc_unlocked (Alpha, 164) 1... eee eee REF-190 
PSSLM AMOS 6 onan bu aye teense Hah See Ge UE ee a Oa On ee oe REF-191 
PFCTPOS secs ek ek a ch Ade ee ee eA Reed a eR Oe REA aden eae ees REF-192 
PCS so oie aaie pide ce esche eck Ge awe enty are aioe wae eae Sune aa eueteuis acta se evenenate REF-194 
ISCLWCSe. ona e Seek Aeon Gade CHEE BPE A EAS Re eaee ae Oe Rea as REF-196 
FOOT WS ia pose od nha berate Dae aoe bak eae Gh aate Bde eae dk babe day ate tate ee ays REF-197 
GICNG iene ce is hee Le ae OR RRR a Bae ee ea ee Dae was REF-199 
finite (Alpha, 164). ee eS hae Swe be ewe OD aw ae he oe oa ewe dg REF-200 
flockfile (Alpha, 164) 0... ee eee ees REF-201 
HOOK 56.6.c% pas ene wo weioins bo Maw dea oie kbd ho aay dae ww aiehe «boas REF-202 
fia, (Alpha, 164): $3.3, 65 005, eek aye, ay Sai 4 ae ek a, ee ae a OE ae REF-203 
fax Alpha, 164) 23 6 Okabe ae ER we Cad OER ER ES TRE Weed eRe GOR GOES REF-204 
HMI (Alpha: 164)! 4 a eaten da pie ee 4 bipedal Dy dawns badd ead ayaa REF-205 
| 0,6 a a a REF-206 
10) 012) 0 aa nr ne re REF-207 
fp_class: (Alpha, 164) 2c ccs c eee dee eb ee eee e eee ee deh ede e eee Re eee eS REF-209 
POAthCONt 5, se bs Gb wd eed ee ode Ped e od awa bbe eee ewe REF-210 
fprintl...ccacib eGo ewebewe eee hee eRe eG bese bbe ds Rei debe es REF-212 
PPUtCs Seow inwdns noe ee Shee Sawn She oe ee ed on awe he ee eta & Seon REF-214 
fputc_unlocked (Alpha, 164) 6. eee ees REF-215 
PPULS iss dhe ee bos baw sd ba ae a Se bebe PAN diate gaat dh wes REF-216 
fPUtW sc.ce a shad chde ada tdeadiaha chi dediatceta ka macbd aadawats REF-217 
POUUWS «sere io eid eae ela ee Sie x ie Ok ee eA eee io ORR ew le ee REF-219 
fad! caf nee. dba e hed CAR hee dba ROMER RA Soe Aba aed ea SA REF-220 
PHO se sscsis es aok wee Ge dig OSS Dae gah aod Hoke adh ela haa db ook wae hw ate tated ed aes REF-221 
fCOPEN s.cc08 i nda ed BAe eee hae eee a ealna ben dd anten ARM aes REF-222 
PEEK 2 gig tree ew eed ne hese ee aaa te epee he a tenn wate we ee eee eae REF-—223 
TSCA ie. 5 oo Stese ats aot wh esate as abcde oad eo gas eas do Gs te ee REF-225 
{SCCK si.5.0 Geb ee bead eee dee ee R EL eG Ete bebe Ge ehde dene bs REF-227 
TSCOKO is 5,5 aca Boa. teats Werk dle dle ae Ba eye Ea eae ae a, ees ace ys S REF-229 
{SCLPOS «ete ee ee betes eat et tntes de ea et een Gamers dedeee ead ews REF-230 
PSCAL si. 5 apie e oo Gettin ais ay Mae ee Sete ed apy Oe Ge eet eras ee REF-231 
fstatvfs (Alpha, 164) 0. eee eee ene eee REF-234 
PSYC eis, dix cira hbo, se as BA ee he Oe ae Se ae ea a Bi REF-236 
PSM es hes casts aa fe aties teases Ge Sicha a Lane Oe ee rate ees BP REF-—237 


EGCG scr carsete cae eass e ete ae ide 0a te ae te cel lense ta Ste as at nee totes wide es REF-—238 


TIME 2eibedicaawead thet acbducon heed bea w aed bhanaeeaced Ba dewiies REF-239 
HtruNGAale: «beaches abwadieeea eee hepa ddeaneees a watiada byadwuus REF-240 
ftrylockfile (Alpha, 164) 6... cent eee eee REF-241 
TW ote eee data pherGotene ba dotee ena d eden cs doedawe se eere wes REF-242 
funlockfile (Aipha, 164)" 4 4.5 ses Bob Gate ace nd a bdwloha ele eae) Sete du REF-244 
fWalteiccbhactade di Gekadeciedleddud ORCS CLadedaetedadea des REF-245 
PWIDG ois che oaay nS’ Rs & Oia we he oy he aha e Bbw ae ey eae ey ae REF-246 
fWprintl 2c ccc ce bee veadaee ete ee eed 4 OCeSe RARER Se Ea eR S REF-—247 
TWO TUGE 5 Nee ck > ope ete Oe yee er ees Paap SI aes Ew a Bin anes undp ee ahaa Ge ne REF-249 
fWSCANT . 3 oc.ce i deb eae God Cede REESR Chae lao he ee Eh ee eeae Sees REF-—250 
CVG oe vu: caster ae ae ley See toes ey a ae pa Mew ers ee pee gee, REF-252 
BCLC: i aaiiid Sime de Bae he Sad Oona a hehe Pals Gad, Rola eee oe REF-254 
getc_unlocked (Alpha, 164) 6... ee eens REF-255 
[WI PCHCH ge a aie te, le di ae ete Rech Anaiee ode ed a ed ed ek Rad de de Rae Rw REF-256 
POL CHAT 3.55 os ise seed fe eee pe ig eae se ie Be: he ge ig woe ak wr lees REF-257 
getchar_unlocked (Alpha, 164) 6.6. eee ees REF-258 
POECIOCK sense, dw age a bk in oe wee Powers dow ale: Mote. ao wb eis Downe toate ee aed wakes REF-259 
PCCW 2. ct bw needa cde eee bata eee de cake eda dead e 2a ae eee aes REF-—260 
eétdtablesizé wc 3c.6 bw S Be we we ME we ae Bee OW ee Be ew SER REF-261 
PCteOId 2 Lita inamierse teed bed dananrebrdtearkeedanaddeaut aa Dads REF-262 
POLED, cig. ariciasibal-a ce dod ia o uo a pe eth Saeed ati a dea. eheen dclea vn Sp ate sees REF-263 
POLO UIG Sse teres ties seo ayes ay ass alia gy ee, aap aay ah Tan aera, PE aye aya eh a REF-265 
POULIN 5 cen dove V Gee GOR He end OER DOES OTRER Ge do LeE eR Eee ewes REF-—266 
SCLOTENE (Alpha; 164) 4 he eR as EER bead bale ee ook REF-267 
getergid (Alpha, 164) 6... ne eee eee e nee REF-268 
Petergid fF Alpha; T68. aca wake dads 2 a aha HHA we eae 8 ee ae Haale, ee REF-269 
SetornaMm Alpha, 16) 234 08s ee RSs CER GEESE EERE OEE OERE SE CE OTRE ERS REF-271 
Setornam Tf (Alpha; 168). bak s he Ped ee ae we Ok ee ad Nee REF-272 
PCCOVOUPS 26.4061 bb bo 48 GOERS ER ELSES ER ELSES OER EL EE EER Od E ES REF-274 
POLIEIMEN: coc ahyed icc ack Gage te matte eo he ee alent ee GAS eaten et REF-275 
PCOS: ed dhe eeda ceed daddananebrdbeaa hed dacaaihedac da Sieds REF-277 
PeCtNAME: 2%. 0 ued dee bwin ewe ee dee eo eae oes, Soe ees REF-278 
RCLODE 4 ated cee tis cdl Goeute RUS @ Bolen inal 6 eae Ra Ss aes ee eee REF-279 
PELPAGESIZE®.. cso. .ie Be a Osea le oh eae Aah © meee ede aaa allo wal, & aw Sere le OB Be REF-282 
getpgid (Alpha, 164) 0. eee eee es REF-283 
PCtPOTP Alpha; 168) soe ew dan bie he eae eee oe ee we RE GE wo eA ees REF-284 
PCtpld sc seas k ied acd ncewe bade vaes Sealnn des bad aeales KRM ages koa REF-—285 
PEL PPIs. 2:70:39 ers ide Reser Sere ie Be eee eG he we ei le bee ES ee ee ee REF-—286 
PeLPWENL x i. o60 dso. ag ae aes bees eS arms any aaa we 55 ee ee REF-287 
getpwnam, getpwnaM_r...... eee eee REF-289 
getpwuid, getpwuid_r (Alpha, 164)... . oe ees REF-292 
CCS 26 a cheek He oa REESE ede ee eS OS EERO dade eh ea Shaee aes REF-295 
PCCSIG (Alpha; 164) seed as b xia Bak pega ed a MST De we yeah ae aoe | REF-—296 
lwIe6tstr. <i a82a oekaw cede chadeade dt Ph etbeeiddenweeeedalen ques REF-—297 
eettimeotday 2.26024. 3404.8 He ee ke PR eke eh Oe a Re Re x REF-298 
PCtUid 4 wevaedade Pid Oee Se eda we EAE OTRRE bas CHEER PEG OTEED OS REF-—299 


xiii 


XiV 


Bs ype tos es ae oe sie we REF-300 


SCIWO os cio Rab a Ae os dEAe CEOS EERR ROTM ERE LEMAR ASO REE Se Bes REF-301 
POtUWCHAT econ se ee barn baie nak badd gate tae.) yok bawece bw ats REF-302 
POUR: cae chew edad chide adle deed dd ade eda adigae ba Dea aude dn eae es REF-303 
IOD (AlpRG: TGDY o.2. echt oc Ge awe encty wete aie ee oR ee Bee ees eae aveanels REF-304 
ClODiCS xc n0.c chee EG OREO ARs CHEE LO SAE ORE EREE Re ERE SS REF-308 
PMTIME, PMLME LT 2 vce ev ne ee nee hea Chee eee nee bee tee aba REF-309 
PSO, wy sia cis @ eee Gace ECR & GRR we EO Ges RE SS Ge ees REF-311 
WAV OO se wists agar Sere ee eee ec ces ehgeee bi tete cat asad RS ve RS ates aD ee nee ur ed REF-313 
ICODV, Sad hg se Gade Ae eS ee ine ae ee eee Gale pe aede Be REF-314 
ICONY .ClOSE iin em wy ewe bo Maw ee ay wk bed oe Mae dae ww eoben bw ans REF-316 
ICON. <OPCD ex. S405, 005 e800 aye als whee | HA a a eh wa, a ee ge as we REF-317 
WlOgh (Alpha, 16D) 223 eee eck ne deee ca eee eb beeen Hebe sade deeeee news REF-319 
[WihinCh's, sit 4b atedaw da pds ee 4a esa Oy bared badd nada baat REF-320 
WNUEX, osc kiaG chatene@ bi wetehee bower Ge bi Gesiebedadeeabhiacke REF-321 
MAIS CP 3 tiieia Snes, oo Oo, de, Bene ee hinas, NE oka Bay Se eae SER ae Behe REF-322 
INItStAte eid obese ER EO CORES Cea EEE SER ORES eee ede Re eae es REF-323 
VPIITIS CH? 3c, ace a oo od ide thes doy ate ache eles ewad & yee ee we Oa sob ete an ot REF-325 
[WItNSertlnh ¢ icc 42Ge ioe beee deel ee eG. eG bese bia asSei aw taae es REF-326 
[WINSSER fond oe ee ee eb Bele Sawn She Eee oh ae he ee ei hae be See REF-327 
ISAINUM 240) oe ddd ceeded deP ded kare meber hier bed dane nheed ds REF-328 
ISalphas gai adam ose ehdwa boa aw ae wk wae Pee dae ewe dares REF-329 
ISAPIPE oie .e Rea a eh eg ea Ge REN heed ced Gee Raa Saeed cea ames REF-330 
MSASCI, dcrgrcie wood e aateriarctiace dt, 2 na cients eda aie eet beige ta eee aight nen eae REF-331 
WSALLY, Gece As os oe She ad A eee ia cro Gee ae Aas ee cae ee eee ek Ae ee REF-332 
TSCMGE 6.6.3 dh wee edie whe Oe gobo aod Hae ag ela ewe pooh wae hw abe tated ed aes REF-333 
ISGIPI bcc oak dee ee RA ee Rae eee a talna ban bad aeed Ae Maas REF-334 
DS OR APs ease te ew ed neha ee aaa le pe oe he a tenn wnt wo eee wae REF-335 
ISIOW ORs shed Gon a sibs ey Hats aed ye aD | Se er eee a od HDs ee a REF-336 
ISNAN (Alpha) 164) 5. oh obo bed Se SS ES RES He ae URSA SEES REF-337 
ISPPIUNG 55225 asad 4 ea his ak Sey a ee Se Be ee ea ee Bee ee REF-338 
ISPUNC i edanera dada vb cad eee ae eed eee oO ERAT OR eee eh ee bees REF-339 
ISSPACE: 5h teh obese neds b Me a Se aes Ma Re eee SOO REF-340 
ISUPPCl s.0 6 Ghee ha Med we ha eRe OSES Lateedun bi een ieeebedeteeba we ee REF-341 
ISWAIMNUIM, 295, ieee Pie as BA ee he Oe Se hae See he ea REF-342 
ISWalphas £6 «ban wde ee ove eda e ede wee de de ded eee Pew ER Ew eRe s REF-343 
ISWCRUE inde onside tag Oxia e Sad aa yy ed WE baie ode Oe eee REF-344 
ISWCLYPOsi ces 5 cok ae hake Sea ee eat heae Gare eeaee 4 ie hRae eh eeaekas REF-345 
TSWHEA ccaatah wed etna ceed ete x eee cere heen ie bese REF-347 
ISWETAPA. h 4.0542 2.5 noe RbSe ClO Ra eeE aD MORE DETR REREE SE ReDAE ERS REF-348 
ISWIOWEEs o.c.0 50 bee ban bo aeeee bah baad a alee aw eb yaek baw ba ans REF-349 
ISWPTING cep eda Babe ea eos Ea ae Oe eal OE e oe Oka Race Saeed ana REF-—350 
TSW PUNCE o 6 oe 5k eoece Ge oh Bee ood ain ee Ew eR ee Ge OD ee eA ee REF-351 
ISWSPACCY Ra.5.5 4s k dels AE Dore. Oa dae a ea ean ke eee arsed meas REF-352 
ISWUPPEL® fo5 eenh a heated eee Gem aw ERE be goa aoe bead ee gba s REF-353 
ISWMGICIG oe's dco 4 Bates hace wy tianen doe a law eke Oh ee Ae ee Mele se REF-354 
ISKCIGSI sie bai CAGES C44 CHESS CHU MERES CUE CESSS EOE REESE ELE OTS REF-355 


40; jl JO TAIpAG TCD) hie SS ee hd ey hae eas RE Ee Ee eek ae REF-356 


Wand 482.242 2 Ga Ske Se GAGS SEG POSE OREO RSE E RG OSE EOS ees REF-357 
MA os s-wa seuce es fboresctoyee Seseere sn do aekieere Ma, ose Pe tere sda athe haters. bo gia Heeete eg erage oh REF-358 
1G4a Alpha; 168) ea dace apiece a Rh h a eden doe ea ad ww a ee ee ew REF-359 
TaDS? scjeecbe cated ew Ue ew ee ae wee 2 We eR es SER ete ee REF-360 
IGHOWMN. 2. i624. ceeded e. Odes, b caw oo be dt eaah bard aeals HALA ea es REF-361 
10) 01 224 ea a ee REF-362 
16 =>. ¢ 0 ae eee eee REF-363 
Vy g2 teats eh te ete esheets See WE de ede ate WN Sion een ee REF-364 
leave0K winked ida keba teed ood dana ebradteaa keh adauasinedat aed oes REF-365 
Igammima Alpha; TEM eee g be aoe ee eae de ne ew SR de we dn ange aoe eee REF—366 
Vat in, dees asp kg aap alae ny x cae Gy enews ey ak dee ean ak PE ay a ee REF-—367 
localecOnv: «26 ¢eeA be dade eee beech tee de Sables be eee tenders wes REF-368 
localtime, localtime_r...... 0. eee eee REF-372 
log; log2; lOPTO': 2 hci eked eG bb oleae hh ORE eG EL atee deed ek ek ees REF-374 
LOS TD Alpha, 168) obs sane dads Lae da HSE ee Leeds eaiaw ede REF-375 
lOgb Alpha, 164) 655 6 cceedeb obese des be ca bedeh ob45 KER Ee CEE E EERE EE REF-376 
LONGI: Ba oe Sotietet So waters pees wt oe owaas woe ees Gaeta a REF-—377 
IGQNPNAME: 2.0665 ob bee cere eee bees Fee bee eh ded bee eee eS REF-379 
Wand 4S: sc ewe ak Swed She owe Ste wed She Ow RE Beare Swe RS REF-380 
Wnt, lpia; 164) nan bean bee Shed dace ehbsadsoe heb daceadetadaceaas REF-381 
LPOUN (Alpha TCE 6362 cso se ds waa. y sense, 9, Ws bokseca oe WRKE Y have WR eo db wate Yet REF-382 
IS@@Kiiss cB a and ae oe ada te atta hae cbd sede le oda gacbds eda weeak ee REF-383 
Stat Alpha; 168). se !pc0 oe wee pw ae ARE, we ee Ee ee ew oe REF-385 
IWallic+.c.hb ou dh edih ba Re Rea CARE OA ERR Bead bbw hee als VERE REARS REF—386 
MANOC, sec ad watevd nue e donb advauy eae bade adeathede hbo ae ead REF-—387 
MDI. 2.564 seed ORM eee SAREE AS Sale Mee Sada e RRM e aA REF-—389 
MDPION: v3.09 ewe oe aoe eae ee he wwe bee AES ee ee ee REF-390 
TOE COW Creed dns, 0b esiets up cyan oe g Gas gone eee eee Goad es ee he ee REF-391 
MDStOWCS 24 ncchde bia e see Rede REL SEED Oe LeR Eee e Choe baeeldes REF-393 
HIM OWTC os ssa, ceeapitiag 1a a repay ih ans Bh eas Rg a ae fap RE aa Bi ay ee ag Se, ays a REF-—394 
MbDSINiteAcciecdedheetbaveantertece ee ean ePeme teres seed eeiwes REF-395 
INDSELOWCSs  cpccdii sued dS Ae D 4h Syke a REO £ hee 2 owes REF-396 
MEMCCPY 624k awe es Sh LEGS Cad eed hE eR ELE GEL EMER SEER eae Es REF-398 
MEMCHE xp 44s Pea sw Bale ase ee oe ak a Pk es as Pe BA ee a REF-399 
MEMCIIP isso dese ede EES e PEER ERE ER OTR Se DEE WERED EA REESE DER REF—400 
ANEMIC DY? iarcg o sedi eae aid as ase eo aed ee ayes es hr yd week Hae aaa REF-401 
MEMMOVCs.0 5.58% be RAS Sa ARETE Rat MEARS AREER ARMS TAS Se REF-—402 
MEMSEE dae ous ee Saws Se Oe oe OME EP ae Geka oe ee Nae ee eee REF-403 
MAKI. sched gcse Weed Ohetebedewes Khar bheabetaguhagueea Shee s REF-—404 
MIS TOMA: %.n,, Srey k Guereg boda e eae Oe Re ere Ra One & eae Ghee |G ae toes REF-—407 
MKCEMP: 34 i god. oo Seed a Sete SOLS SER OES OO DARA RS OO OE Ree Ey REF-—408 
TUK CITI G3, 56 setsessahse cw Je aecat wr se le ede sata se io A ees tee ig wea owe eee le es REF-—409 
MMAP is Lbau.d eede dP Ohegdeaed coheed edea ed baud aoe eedPoaeadeé REF-411 
TOG 5.5 S sdaies in Sowa hee a eee, witb Bok bots. dow ahd See. ao ak Phe Doprate totes, wih doh toes REF-416 
[WMOV ES ee. ae, Weta a dc, w yoshi ee ha OS Re aw eee yee ae REF-—417 
MpProtect oc vaece de Piao dene eta eee OES eS EMER EES EE OEE SE EO REF-418 


XV 


xvi 


MEANO46 ee oe oc i ee EL ae ES ee REF—420 


MSVNG ..2 35505484. ne had DROS ae nae eee Ae ee Baas Bhs REF-—421 
TOUTED esac sere. eo wy Rserecs, be ae eee, ee ed a Re Se Way ae bMS REF-—423 
mvlWwladdeh. 0.366 a6 cide ndash eA ae ee RARER A ae eas REF-—424 
MVLWaddStr .0.60 6.00804 oe hee ee bbe ERR See dete need de FR ete eee REF-425 
INV CUE: 2 dane bs ie wee ay We a Sas Ma Rs Ete OOS ee REF-—426 
Mvlwldelch wich. dec ecka Pee ee eee be bh PRE RE SEE ER eA PRED REF-427 
iM VilW| PCC ae. ie aes Pie ae BA ee he Oe ee he See he ea a REF-—428 
MVILWIGCtStY. «can wue se ove ewes e edness de cedane bene ee ee ed neds REF-429 
IMVEWIWICH: fen ede Pata Hae a we oe eae ode oe eyes REF-—430 
MVIWIWMSCH 252202. be bee Eee EERE Ee Ed Ede eG bese ES REF-431 
MVILWIMN SSR oe. eee ae eee ae aoe ee ea ag ee a a ee es PE ais S REF-432 
MVWIM? «0 da 8 bea Roe DaR Ad Bde OEE owen Sha See Caegeaead es REF-433 
Nanosleep Alpha: 164) so. dcce Soe neyra ewe deere deen ees eau down daw REF-434 
MEW Wiles crea ew Gs ee dus nat eumete Gadus dh Raia Guana AMS a Rew Aad ee Sos eal ae ate REF-—436 
INEXCAILED (Alpha, 164) eat ee B, & acti wally wR ae he EE, Oe Sie ERR ee eS aoa ls REF-437 
nexttoward (Alpha, 164) 6... eee eee nena REF-—438 
TANCE: vs, a. eh eek, Stee. RNG Baten, wea a Patna de, Pais whe: Sider im toh bh ae ce dow a Sate act a REF-439 
Mint Gipha: 168 gw s.o a hee aad ee CARED ARG A ee Re EAR a eee REF-440 
MONA se.0 these wis Meee Rak ww be weve OD kars ae he eel oa a Gaed REF-441 
NI VAN GINO 666k eee SRR Ae Rare Debard doer behdicenhecd dds REF-442 
NPANISS oa. eam oye eden bo Marge ewe hw dhe ear dan ewayedoben beans REF-446 
OPCW, & y-ths seth yess, ais, ed ae ay de ese Sy eR a eh ee ee as ee REF-447 
OPCNdis ots ced Cea Cee hee ee ee heehee PRw ee be eee Gee eS REF-—450 
OVELIAY ss wise ¢ beatae ed dy Slee 4 ed aed Gy ald 4 he det ed e REF—452 
OVEIWIILE ci4 Gch adeea Ghd we heh aebiadesae bi eee iebetaderaeeieese REF-453 
PACH CONE e:56's ieee, eae ha eee es des Ne a ha eae ee Seas ee REF-—454 
PAUSe cide hobededeaw ede edaee een ede dw ed bedede eee weber eduads REF-—456 
DClOSC 5. Sided ed gb wed Gd hee ode Ped «eS dE awa bbe ea wwe REF-457 
PCLTOP 62 lake ee teiawh eed che tee seesae bese eiekbebsGeieeeasees REF-—458 
PIPE hc. See ee ew eee Pee See eee eo Le een Oe eee eb Skee REF-459 
Ol Alpha; 164) 2s Bho Ske ae EOE ee hao ROAR ERLE REREE YS ORERE ERS REF-463 
| 8X0] OY 2] 0 ea ea ne Sr ree eee eer ee REF—466 
DOW oatece ct Gis & ons, Ss eal oa we A ne lanl alee Runes Se oh alae REF-—468 
PEGA (Alpha; 164) ascii ieG te a Wie ye ate SOR, eee PEA ee See Ss REF-469 
PRINth 35.2 ow Saks OA Ee Ada Oa hd Gre AEE hore REED oeas eee he REF-470 
[WIPPINEW sed Sodus ede ahs ee goed aod eae ah ele ew ane book eae hw ale tated ea aes REF-471 
UCC? 6 Sete Sw eas ates, 28 Glaser ect wl Gl teeth Gut aie Soe a awe ak aa ce REF-472 
putc_unlocked (Alpha, 164) 6... eee ees REF-473 
DUGCH AR a eteca era ce tre, aod wed a paid es bd hg Pals we HEE Go GO ee REF-—474 
putchar_unlocked (Alpha, 164 0... eee eens REF-475 
PULENY 3,405 esas gata eae ge ae ee Se Be ee ee ee ke ee eee ee a REF-476 
PUUS 2 adcvanere dada ve bad eee at eed eee oO eA AES Meee bees eh ea bees REF-478 
DULW.s asters ots aces ote we ee aes Mae tae ee REF-479 
PULWG 4 6.05 eS ha ed we ha eRe ees bated bi een ieeebedet aba we ee REF-—480 
PUtWCHAT 6 sc'ato eee ie hae BA ee he Oe Se he BRS ae ea a REF-481 
PWHILE Alpha, 164) vce be Pie CLS SS ELE RENS DESH OES SS bas CHS DO EURO SS REF-482 


abs, llabs:(Aipha, 162) oe wie ce ee ewe SE Be we Be ws ORE Oe wR EE REF-483 


Qdiy, lldiv (Alpha, 160) iaaciee ccadaneeibad chee aes dgvebibas Sh oRaws REF—484 
SOU peers ay aye eiieavs, © eee terete, ane at sere a eee ew ae Panes Do eee ees REF-485 
TAISC eb as eo SS. oh ds Ral Gime SAGA Sue bo Gus AG AAS RA Ba, ae des Ral eee REL REF-486 
PNG, Wea Meee ce oe. actos eke otauses oe ws Gah tes eS Bee 4 ae Een ee eS REF-487 
TAMIA OU Nis oh oe ve spate esd Ap Mateo ak Spee eer teed any MDE pa eres EE Oe REF-—488 
[NO|PAW a2 4 oe adh ORE EEE beeen bk PRE SEED ed eee PRESSE REF-—489 
COAG GS 5 cote yep a ss dc ate ays oe, ho ay ee ah ates a aia hea aye eee Be ee ee ee REF-491 
TFCACCIT: TEAC: T x85 40d.as Sealer AG WES BOER RARER OES OER ES REF-493 
readlink (Alpha, 164)... cc eee ee eee eee eee REF-495 
TCACV Alpha 16D)” 5 Go ea hes ho bE EK ES Od RE BSE KER Re eS REF—496 
OAM OC™ ascot as hg, Parc ayles ay he tains Gy eens ha ee eg ela & Matias, asters aegis By de ee ae REF-—498 
realpath <2. cd eche deve eeewd ev sede w eve ed ewecesedew hee davewwes REF-—500 
[wirefréshs .M.02cs ded wanewe aya bee doe sav eee de ee tee ad pau REF-501 
remainder (Alpha, 164)... eee eee ees REF-502 
VEMQUO (Alpha; ID) ie 5e acai we lp ee ae wee eV ee SR gee ee ace wee ie ee REF-—503 
POMOVE: 2 24 oe. denies AR aes Sa AEs AE Sawa See eae AE aaa kes REF-504 
POMAMC esis oboe aie Seed ge donk tenes, hue whe Sade, e, aod ed noe Swe eed Sade wae acd Stn REF-—505 
TOWING. cb dcawes decade eee AHaE eRe Ca kee ae Cee ae eae eRe REF-—507 
PEWIMACIP se. eee Shes Sw a Be WE AB wee a Be OWE Re ow SR REF-508 
PINGCK ed Lineker e tre t ed dana webrdtraa vee ddwaavedd Gaede s REF-—509 
TMI: (Alp hes. 164) 9 eb hace. e, bp aha eee wb Geen ho) AL Sate wwe hed ave, doe Back ates REF-510 
HTM UE asses terns he, PSP ayes my hx aha Gy a a new eR ak dees earns ak PE ye he ee REF-511 
Sbrk vad ces Ooh been ee ewe eed OER Tew eed eee eet edna REF-512 
SCallb (Alpha; 168) dsb ied aes Mgt ak kw oe Baad Gey Bed CE aE EE oe REF-513 
SCant ois fia ee deka hen whee ene EA ER EOE Eo eee Ee eee ed REF-514 
[WISCANW <<. 45,0 des wate as des See hae Sake ee oe ae eee eee a REF-515 
SCPOll) 642 eve eee bed He OE eee ENE WERE Eee OE OE ENE EEE ee RE ERE eS REF-516 
SCPOMOK 5 5 e bk gb wed ed ee ode Pad « od aw we bd eee hea owe o REF-—517 
SC6d48: oc eheh cheat ieeb eh eG eh been bee be Gel ee basceeiads REF-518 
SCOR GIT ory ee 8 ie Bic le Sew in Se RWS eS hw a ee Oe Ee Bae ee REF-519 
[wIls@tatte .2 2c ccaceau cee mod dace a Shbad doa ee Mead deaewd acre ae REF-520 
SCtDUE ceding eet iinn bo ata ae ek eae OMe e dae byes dd oaewes REF-521 
SOLON Vand < 4 hes ones ec ato RUE & Se MD Aled! Ge OS A Se eee a Rae REF-522 
Set@uid: Alphas 164) ws esc wee ek ee ER ow ee OE eS ee REF—524 
SCUCId 6 hak bho aha heed Bae he REAR ROR baw Ghe Ale od Reale are ed REF-525 
seterent Gipha, 160). nsuw eed vinn se bores oma Ge hea ea de eee tae eo eh ea ae REF-526 
SCtILIMER. cca.s cee hea as cea baa ee cee aca ac es ee cage tees oe eealee os REF-527 
SOLJUND, oiice'e so. ee Betue ug sis Bo ceae et aiae T.ce eta eee te ta es yee eh a nee eas REF-529 
BOG CY scenes canta pe iataes tas ty abed tes ey d ceo emp ata we Spades ane) ees ee bee es REF-531 
Setlocal@:..ij.405 ecb iat ieee he @ei eG beee bebe be@etew bende ehaws REF-532 
SCtpold (Alpha; 160)... ha45da as Sa ea he He ea ba eh a ea Be She gee ees REF-—536 
SCbpStp Alpha, 162) bceaheviee nr bees eo eae OER ER SO ESTA Ea OEE HE REF-538 
SCUPWENLE. 3 a. 44 taraiand ds ated et Sete are tnd dob dbs Wa ba aes Dees REF-539 
setregid (Alpha, 164) 6... eee eee eee REF-—540 
Setreuld Alpha; 164) snc enone oe ee EERE eA eee ee eRe es REF-541 
S@tSid (Alpha; 164) .4e che ede ee Eee ERS LEO ROR OREO E REO ERE eee Ee REF-542 


xvii 


xviii 


SECS GA Ge ec vaste sete kee APS nen os gs Ae ne PO ae ey REF—543 


SCCUIG pa cts Seb ae gered ask eee ean Mab aeens eb eeeeenueae aes REF-544 
SECU OUP a zie: rgere tatoo ik Sree ne ariceee meio ee ee omic Me eae eeees @ REF-545 
Shm-Open (Alpha 16H. os anda des PEER REE OER OE PERE RECS DE REEEES REF-547 
shimunlink Alpha, 160) 63.5 cos are le eRe ae Bh PE Sa SA PRR OSE CS anes REF-549 
SISACHON Ss grand 6 Od KG Ae AR GR CORE BOER EAR SAGER SORES EGER E RR ORS REF-—550 
SISACASEE e¢. sieceg bo ik Doe ae Gone ae |G ewe Ske wd Se ee Re ee ae REF-553 
SIPDIOCK. 20005. 2a ada ha RM aE OSS EMRE ER A Re ae oo CRORE Lawes REF-554 
SISdEISEE e-cc 4h ces ee hee Gane Ae ew oe Ree Gale ee SO ae Oar eis REF-555 
SISEMPLVSCL: % 2c bod vo RARER ELE AEA R gM EMEA EE ER RE EEO SEES ES REF—556 
SISTMNSCL wx. ¢. eee, Oyeneerhag boi eee Ge He dee Pe ee ree hehe gs Sa REF-557 
sighold Alpha; 164). 2,05 aes area as wie a eta a ae a Se ae ae OR we REF-558 
Sigignore (Alpha, I64) 0... ke ee ee eee eee teens REF-559 
SIPISMEMbDCH a) so alan nd we bdalOe Dad Hata DOhe Res bbdedaed a beet REF-—560 
SISIONPMP ine db adieu $445 454 945 6 aoe EASES EES Late Ree wee REF-561 
SISMASK psn d nwa eee As baie wn does MeO a ha SMA wE Oe Seeks HORE REF-562 
SISAL £ oubk eben week EE eESS SEER TERE EEE OHSS OEE E ERE EEE OHS REF-563 
SISPAUSE nti sues be ba He ee be weewa bee eee SOE ea Oe ee ek ee wee REF-564 
SISPCNGING 0445 chek de bead bee Eon SSR eG SESS SEE ROR SL aE Ee ES REF-565 
SISPFOCMASK 3h eS iasie Shwe Dade ORS oO HS Se ae We eee Shee Sane REF-—566 
siorelse:(Alpia; 164)! «4.00. eeadd bed ed baer Pebadteee wee der weead Ges REF-568 
SISSCUMP: 4.5. 94.4.4 a4 whe, bo eta ae hee aoetiedae aa teiens bee REF-—569 
SIPSétMasK ji oka c ced andadeead¥edawed ake atceduheadcedundakes REF-571 
SISSTACK (VAX Only) eg win 04, & oe ON a Oe OE A wR ea ae ORE ew OES REF-572 
SIPSUSPEN as vee atehacd ec dea dee es cei debes Koad eewadeinedea ss REF-574 
sigtimedwait (Alpha, 164) 2... eee eee REF-575 
SISVECs c.25G keke eS Ae RoR REGEN SOAP OE OS OR NERE OS 6 AREER ERM OSES REF-576 
Sigwalt (Alpha, I64) 2... eee eee eee eae REF-577 
sigwaitinfo (Alpha, 164) 0. eee eens REF-578 
SIN 665 S GAS SES SEAS SEES SHS EERE SERS E LES EELS CSR ESN ESE ES REF-579 
S025 re ay id wg re es ecg eee oe eae ase ey Bee Tap As een) Eee ay ay bre es eas ery ee ee ae) ee REF-580 
SIGCD is 4 bdewo se dade dh eed ee ates dese eh sen ben wese dade sheet bes REF-581 
SNPLINGL xcs 4 wy aerinats o palate D 4b bao es oe eran oe REF-582 
=] 0) 10 Sg ae a REF-—584 
SUG <a te. 5ycti aig cee see 2 Faas. ae, de aye a ad we SP eae ney wad ee ate By eo REF-586 
STAN fo0s34 ec Raa ERG eed EOTSG SEAGER EO Ea OLS ORES ER EE aOTS REF-587 
SPANGAG vg, sity pgs pas ye eerie ee Gab das Beis oe seed ke ah Bes ee ge ete ate REF-588 
STANCOM sen feos Rete hes AGE Gas MEARS LE See Lees REF-589 
SSCAMT y aaeie er ate eyes cae ce aio ie ie a STE cee a net aa eS caeae ue atarette REF-590 
SSIONAl 4c eae eek an ea chee these eedarea dvew Lteadeedaeeakeea des REF-592 
Pwistandeng, b..04 ovankducen bua degen ou hededd patious ae ue dun oni REF-593 
[wIStamdout: «8.6 6 5.d.u Gre eal aie Oa BSH OE AEDES ORR WESC Oo EROS OS REF-594 
SLAG fie encase oath ce arte, She ots, © anelele aaa ete ere ia ceAl, eae eV orate, Ra ewencahe oct. w awehunate REF-595 
Statvis Alpha TOD). ° ood +.hciee ORR eek eked he EoD RRS REE he Roe PR Ks REF-600 
SUFCASECIA P< oses. s dd anie teas ged wok tate hw aS ew aw ah doe Sa ee aa 4 REF-602 
SCE CAG cach nae, don Soctne a diss gpa Sas, Ss aul cep Serna aids sw Gy A ae Sonal oy eee ees oie ay ea REF-603 
Strch? ..¢o234 6 eis esa be LUE OHS SW ETEMERG REDE OTSS OEE EES EE EL EOES REF-605 


SUNCIND. ix,. 4, erate bathe WAS abs. Bee eee As Wea ap eee A es ee i ee REF-607 


Stroll. oad nwa chau Chee ebewane Mebane be Re baag aeaaean Oba as REF-608 
SUCDY «cus oy iba bea bye hbo Yan haw ae yack dares be are eas REF-609 
SENCS PM d cis ac wud cos Gusset a emustin BLA BGA Hh Oe OS BUG awe ns al elma Baw REF-610 
SEP: eas veseteee ose Ee ecei ere te eg dene he oe ie ere ue ue ase aaniere alae ees REF-611 
SINCMVOR 025 aw. f ha.date hea ea Oe we Aone 8 eam aee hae Ae aes ates aE REF-612 
StIIMOM> fae cb ware eae ge da a eae a Gate Bowe aga keane walter dana da ale wae REF-614 
StrTtIMe: «dace deeded Cee a AOR MEE A RAR eR Aaa ea eee Be ee a REF-618 
SHIEH sede eee Re aw SR eee Re hw nee SORA eRe eww Sa REF-624 
SUMCASECMD 5. gcc aceewd dee ded cage ee eee Ohadaw de geeadeawd dae A REF-625 
SUNCab «64 UaGelae bese ie Gh eaceiae $440 64000440 0beGb ene ao ESS REF-626 
SUNM CMU a2 e548 5 ard apie, 8 gees Brg by Bin Bea ay ieee a he eis e ECL as ay aio eee REF-627 
SWOCDY ste. peru deebed eed ced ethwads ae PRawee de Cae Ore bee ew wes REF-629 
StIMIOM ic, 4b alanis aed dss Melee 4 ed grad Gy Rad «bead ob eee eS REF-630 
StPPbrk « ichadendehiwten eee etende beeen ee dadendedieceidGes REF-631 
SUPPUME seco) sea Aa Wa higes bea Bad ake baa de Ree eae ews Daa ds REF-632 
SUITCHY 6 accu w dee ec teedane ein wee awd deeded «ened h bees eeene ee REF-637 
SUPSCD farsa wae got set ee Saas Doe ees by aeaees oe eee eau REF-638 
SUWSPD ide baGei aw bead hebebeateiak bead bibGe band cued bad ede uns REF-639 
GS ORSUP sa. Sise ase epoca Gupte ei uteue te Wines oie euaiteess. whee eeNgee ec heuarie oee ia ees REF-640 
SUI0d 6. ocd dco aiwau d ta ded hace eee db bee ded dd cena wake baa’ REF-642 
SUPCOKS SERCO KB sb oease bs soale erage baa ona wae, wee eben SoG REF-644 
SUItOl, edie da deh dus RAR ea a eR led ee ead and whew aa ae ae aa REF-647 
strtoq, strtoll (Alpha, 164) 6. eee eee eee REF-649 
Strtoul te a.d head Bead Reed bad DOO ERR eR baa Chea bama dhe deed REF-651 
strtouq, strtoull (Alpha, 164) 6 eee ene REF-652 
StrxffM. . dc cecbdakcaacven dae ebh aealed Gen bddaaweh actagawe dk ds REF-653 
SUDWIUM, ode elon SB de oa BR eR De we SRA owe Ee ee eos REF-—656 
SW aia eras bs ws piesa tae Gy abedtes oes es rahi esate we Spa asad ans a) ao atatate @ apaie eases REF-657 
SWPrintl 0. i4.4c oboe b dee Gee eee eho ee bE bee eee ee eeeelees REF-658 
SWSCAUE  o5:c00isi5 aliases Abs tae Ba dea Wed as yd kee ale Bia ee a eee REF-659 
symlink (Alpha, 162) cera ede ee ca hese sess eedseecsseseneereeseeees REF-—660 
SVSCOME 50 6 dap deen aed ey Aa 4h toi ed any BETO we aera & yaa Se REF-662 
SYStCM g0ciadeianke eked e dtadieg heehee bee baal ea eee REO ER RES REF-669 
GAT shag shia eet 2 Sead hoe. SN eae de ay ae de we BP eG deel ney a ee eh ae ae ee eee REF-671 
CaN esc eee dese ect etase ected deca bedede Seam ee bree nedar eee REF-672 
POM GN se anes oe Sh ates pad es wes eas SU es es OR ose wy he ee Ee es REF-673 
CEMPNAM so sobs SARE AWE RARE AE Ree EE OOS SCORERS EERO SEER RS REF-674 
COAMMA Alpha TCD). x20. oi Se Bee oO EER ee Sah Rae OWS Pe Rw a ee RRs REF-676 
CUIMNE?4, 66a Sn wiae eae Uh Save eae aus, eh dels A Rk meee eck aaa REF-677 
CUMING? essere ce, oo gion Saeceee, & ceey attence te, aes tate seca, ee wy a see ese hosel ase de area, Be ee en REF-678 
LU PMS: 5.34 bs od oe Seeded wees Sed eRe Od od OS EO SAA Res. on Seed aes Sele REF-679 
CM PNAM 49.5.6: ie oe Re ane wee eR ae eg EE OR GO Ree ee Ee a le ee REF-—680 
LOASCH 4 aie saw. Pa dies Ae eas GRE aes AE aaa Gee Ae eee eam mere de REF-681 
HOlOWEP occ b wae tw ne bade ahead betwee dvuds beeuteaaedededas REF-682 
MOMOWER 2 sn Sani hd & yin ee Ane eae nda by Oe eG Ae ee Rae de bees he REF-683 
COUCHWIN. 2c. cee be Pee adee eee EN SOE UE OES Se Bee eee ES Peed ese eS REF-684 


xix 


XX 


COUPPOR sas tench decatig atk Sue AP we SS Wee ee ee PS ee ke Pe REF-685 


-HOUPPCPs 6 o.80Gakanad chad Seew dha Gare Sheers he Mb hee awsae Sos REF-686 
COWCUEANSG sc oye. ood dues bees bw hee ea ew eo wah dines boars REF-—687 
towlOWer whacked che edad ceed dd adeeda adieaeba bea ach dn cae des REF-688 
LOWUPPED ee kk cee oe Ri eon wie le Peete ee oe OA OR Ree EEL el wes REF-689 
tEUNG: Alpha, 160): wid ne does dP hed k Oo AR EAR EERE EEE hea RRR SS REF-690 
CLUNCATC! 6 bik eee bea ee oe oe eee hae Ree oo a Oe he RR ae ee a REF-691 
tiyniame; tiyname fo. dak wee es A de eS EA RR ae ee as Re eRe Oa eae a REF-692 
CZGObs oc seca Bate oe ee Rae le Gules be ae ee RE A aS eae ONS EE Re Sees REF-694 
WAlATM steele ohare ieee dk Hak aod kane mabe herded hanagkeda Xs REF-698 
WMASK: 6 .i tides Gebea band Hole es beled died beideesheligdesd cs REF-699 
UT ATTN iss 5 erste ay eas ai 5b eae ay te Gast Ss eres de nse RP ee ae ee a ey REF-700 
UN PCC avin red ovae eee ded aw seh eeh wOER EET ed OTR CORE ORS REF-701 
UNGCCIWG a Heke Samed bee ed bk Gea DS eawekd bhai nedeeeee REF-702 
unlink (Alphé, 164). scene hie Rek eS bh we NG ORAS RES ECL at Ee GE EL oe EO REF-703 
unordered (Alpha; 160) sia bs ei tise des Se gd RRR ka eee aes eae REF-704 
Wnsetenyv ase baau dade ndeadase evn ede de et bed ade ees wea de edaads REF-705 
USLCCP is. 5 aided ei gb wed ead ee ode Ped e Sd Sawa bbe eee wwe REF-—706 
UUM onc bidet eetelawh eed edaetdeeseesae bese bivkebsGeieeeasees REF-—707 
WLMIMOS 55-2100 occa ci awa k bea ee oY nee a eyed aoe & Saree REF-710 
VAXCSCRELMINID an pitied a ihe Reed daine ead eae e bea ade weed Oks REF-713 
VAXC$ESTABLISH ...... 0.0.0... ccc eee eens REF-714 
VAAL OS oie oe gitin a GaSe Seg a See BK a GO a led GE e GRA Ba COR eae aes REF-716 
VAL COU MG sod eid te see ie OM, ow Wie Sle ee aR SEM, © nee wg OUR eee RE ew Oras REF-—717 
ValCHd 2.4242. heaw deeded ti daa bbawd bodied es daa h baw Gdediecd eee ds REF-718 
Va-start,, VA-Start snc ocx ocd ak Wonk a Sw ayes © Gee eae Sao Woes Gah WA waded wD Aye REF-719 
MOTK: a scccbaedaaneed ARMac ewe bade eee Realann hee baa aealtes A Maes REF-721 
2) 0) Gc cl Se ara en eee ee REF-723 
Wis CAME otis, ose Goo ave es ep Seite, sd Gye goes 4) pa ened Gm aes a ee REF-724 
VIWDEM oicinc back ede oe Gee EL ERED Ee Pee R bse bite ee es REF-726 
VIEWS CAINE in tains eg, ee ap tig Aare ete. ey ie aes a eral a a are ape aa Ba ees EC ae ay tis REF-728 
Vprintt 2 sceuceeie ce dteeb aventcet eee oh een ePemees deca ee eet eee REF-729 
SCAM cb aaates etek 4 spate eased > 5 MatePeoe copa eters tend any DENA Spt eyes > we REF-730 
vsnprintf (Alpha, 164) 6. eee eee teens REF-731 
VSPIUMNGh oh 5 4%, cicte aeapieiaa in ys a's kc 4a ge ane Yaa a Pe REF-732 
VESCANT : o2ace cae de ee ce teteee ede debe ca bedete Hane ee ee neds REF-733 
5210101 2 101 6 vee re a Pe ae ae REF-734 
VSWSCANE. ccs i dank ceca cacbaes.s adak nen aadakees s dane eed deaaias REF-736 
VW EINE 6016.3 ee ork Eee eee Eee Be eS ie ee aE ee Oe REF-737 
VWSCANE o 24 .bod ieee Obed het ebedaues Shad hea eed cea Rhea Xs REF-738 
Walt «4d 0sk eyes bord ean be ae wins Oe hea ae A ee eb oe bere g boars REF-—739 
WALES sane h a8 a and ate doe dedi aie BBR a anal doa adi aah eRe a Gnd aie Seg adi aes REF-740 
WIE se oeteise ig wh He settee ow Je esate lee de atta see BUA be tego ig OR eeu a a we abt we REF-743 
Waltpids.: d004b20.0eedee de. Oden b cand ood cdt dead bard aedwedea ds REF-746 
WCECOMD 5 26.3 Sendie bowrahe wwe, nib dod bones, 4 how ale Soke ow ak he Doerate toe wane REF-750 
WCSCAL: aici’ de «ates dee ya en Sea ew edn Wa en ce aw Nee ds we pla REF-751 
WCSCH 2.ct¢c4 edu edad Petetene edee dese ecbetene eeuedadePeteda REF-753 


W.CS CIID 3 deers heh ats AP eG antes Eb ee, gece RPS ee Gs eee CA ete ape ee ae REF-755 


WOSCOll oct dato ached Seer che wawetabew hho Paha da dorm ba hia oe des REF—756 
WCSCDY 2 ae owt buen bo alee a be ed eee al eae ee Wades eo ea ea REF-—757 
WCSCSPD: ok. god. cb Sen ea Geeks BES See Oe AOE R DES RE Ce Ee Bae Boek REF-—758 
WCSEEIMN Cs. 25 a: sere ce He ace eae Oe ae ee Se, Oa lo PR OS BEER le Be ee Be REF-760 
WOSIEN: a6 28d ded. eoR ERR ASO SOR EERA eRe aE ho dld OR aided he Ques REF-—766 
WCSICAG. soci bag aig eee ae doe te he ae Rite oe ah Oe a Be ed Ae REF—767 
WCSDCIID: coor Lake ac cek Rhee TRS o BREE wR RARER OE Be eR ee REF-769 
WCSNCDY sa. ee ook Saree eRe weed Sek Outs ae eee Eek wed ee REF-770 
WCSPOTK cco dace kee eds e deed Dawe eke hoa dee Daeg wae wd’ REF-771 
WOCSECHE 62340-2244 40%4 $008 44 006848 4404 F040e eo Seledeeateelads REF-772 
WCSTLOMDS . 044 facts yale ed gate ae tbe haa dee ahs bw eee REF-774 
WCSSPD si ce deve See GOEUee ced eTReotede Pe eena de dada badebes ete REF-—776 
WCSS iss ode adh dei eed bd ees Reed xR See REF-778 
WCSLOG «426 adee4G¥ i eG64 +4b¢ 00 S04 S4 CREE EL aden dete taded aud REF-779 
WCStOK 4 be-4 cobs ds tahiewes dees Sew ada eee ey he eee eee A REF-781 
WCSUOl 4% ecsededee Ceedes eetucee dee U4 GgeS 4 bea we eee Ce ae ees eS REF-—784 
WCSLOMDS 4 2.4628 sue baddtawe bode Dende Sdote4s eA ede hae hoe eels REF-—786 
WCStOUl s 42 i106 44.5458 404854 2006S Oe $49 R SOs E EL ERR ESR SEER REF-—787 
WCSWCS) 3.4 eee eS des Ga ANA oe Che d She eres Sha OWS ERS ee ee REF-—790 
WCSWIGth 22.4.i cee heed bse Raed Dawe DRESS EER AY ERRELORADOE RARER ES REF-—792 
WCSEIPM \.3. a cat dan boeheenae ewe k bane Pate damewwatde d bowled REF-793 
WCtOb 6.884 sa chk peda Ree e bh skated ded akee ake wacbh asd adowe as REF-796 
WCLOMD 2. 2 ais ane ew Wie le PRS ae aoe 2 ee eS a eee Se eae REF-—797 
WCLPANS 6 caw che hk ea RO hee hbS EE BER E RRS AOS ORES GES Caw de eee REF-—798 
WCLYDO- & veins bse aot eek ae Gack Goines Sw wie we ee a eh ee eh Hi en gd ho ees REF-799 
WOWIdth:« 6 ape oh Ge A eek ARE OM ae Dee bh RADE RO RE SERRE RS REF-802 
WIMCMCNT 2 4 sx04d ded sede s Sods CHEER RE KOT OS Sods CERES CE OTEME OO REF-803 
WIMEMCMP: 3.5.6 ose bh eh wea bode Deed OOE heals oe owe Pee eee REF-804 
WINMCINCPY ci 4ccbdeheatedakdba@ecaebbad pba GbenGedaeu beae ehatees REF-805 
WIMEMIMOVE: 3.20 decks a, dia ee Be aie Re a ak eh gy Re EA a ee ee REF-806 
WINEMSCL 2 adage ve bad edie des deca eerae OUawe rad Gedewe oe dagea ts REF-807 
WDIMOAUE as ¢ 2 eet se bb aD ae SA ee sy RIO & ese ea ee REF-808 
WIAPOK 4.63 6.40068 ede PGs 0G Ladled beg oR SEAR Ee Oe eRe ES REF-810 
WHILE: aisha ete A a © Bala eke ee a a eR ee Ae ee EAs is, Ran REF-811 
WIILEV s 4c bcanda dees aedeke edb ede be hae eeaa we beenwda debe eadee ees REF-812 
WSCA 6 inc bo acne dae Oo dd Oe DHE EOE Re OEE eae oe de a ee ea REF-814 
VO V1, Vo Alpha, I64): 6k a cewek ROS SAS Oe Oe ORE E RSE ERR Re wR RO REF-815 


A Version-Dependency Tables 


A.1 


Functions Available on all OpenVMS VAX, Alpha, and I64 Versions ..... A-1 
Functions Available on OpenVMS Version 6.2 and Higher............. A-3 
Functions Available on OpenVMS Version 7.0 and Higher............. A-4 
Functions Available on OpenVMS Alpha Version 7.0 and Higher ....... A-5 
Functions Available on OpenVMS Version 7.2 and Higher............. A-6 
Functions Available on OpenVMS Version 7.3 and Higher............. A-6 
Functions Available on OpenVMS Version 7.3-1 and Higher ........... A-6 


Xxi 


A.8 
AQ 
A.10 


Functions Available on OpenVMS Version 7.3-2 and Higher ........... A-7 
Functions Available on OpenVMS Version 8.2 and Higher............. A-7 
Functions Available on OpenVMS Version 8.3 and Higher............. A-7 


B Prototypes Duplicated to Nonstandard Headers 


Index 


Examples 


11 
a4 
p26 
2-3 
2-4 
3+1 
3-2 
3-3 
3-4 
3-5 
3-6 
4-1 
5-1 
5-2 
5-3 
5-4 
6-1 
6-2 
6-3 
6-4 
6-5 
6-6 
7 
8-1 
9-1 
9-2 
9-3 
9-4 


Figures 


xxii 


1-1 
1-2 
1-3 
5-1 
6-1 
6-2 


Differences Between Stream Mode and Record Mode Access ........ 1-52 
Output of the Conversion Specifications........... 0.00000 eee eee 2-20 
Using the Standard I/O Functions .......... 0.0.0.0... cee eee ee 2-22 
Using Wide Character I/O Functions ................000 eee eee 2-23 
I/O Using File Descriptors and Pointers .................02000- 2-24 
Character-Classification Functions........... 0.00.0 e ee eee eee 3-7 
Converting Double Values to an ASCII String ................... 3-8 
Changing Characters to and from Uppercase Letters ............. 3-8 
Concatenating Two Strings ........ 0... cc ee es 3-10 
Four Arguments to the strespn Function ...............22--0005 3-10 
Using the <stdarg.h> Functions and Definitions ................. 3-11 
Suspending and Resuming Programs............. 00000 e eens 4-15 
Creating the Child Process... ...... 0.0.0 5-5 
Passing Arguments to the Child Process ...............000-0005 5-7 
Checking the Status of Child Processes ........... 0.00000 eee 5-8 
Communicating Through a Pipe... ... 0.2.0.0... ccc ee 5-9 
A Curses: Program «3.06 25.094-4 44454 4444005 080504054 404b45 05% 6-7 
Manipulating Windows ............ 0. ccc eee ee eee eens 6-8 
Refreshing the Terminal Screen ........... 0.00000 cess eee eee 6-9 
Curses Predefined Variables.............. 0.0 eee eee eens 6-10 
The Cursor Movement Functions............... 000 cece eee eee 6-11 
stdscr and Occluding Windows... ......... 0.0.00 cece eee eens 6-11 
Calculating and Verifying a Tangent Value .................005. 7-5 
Allocating and Deallocating Memory for Structures............... 8-2 
Accessing the User Name... ......... 0. eens 9-3 
Accessing Terminal Information.............. 0.000 eee 9-4 
Manipulating the Default Directory................ 0.0000 9-4 
Printing the Date and Time ....... 1.2... 20.0... eee 9-5 
Linking with the HP C RTL on OpenVMS Alpha and 164 Systems... 1-6 
I/O Interface from C Programs............ 0.0. 1-45 
Mapping Standard I/O and UNIX /O to RMS .................... 1-46 
Communications Links Between Parent and Child Processes ....... 5-2 
An Example of the stdscr Window .................0 cee eee eee 6-5 
Displaying Windows and Subwindows ................0000-0 0s 6-6 


6-3 
6-4 
12-1 
REF-1 


Tables 


Updating the Terminal Screen ........... 0... eee eee eee 
An Example of the getch Macro........... 0.0.00 cece eee eee 
POSIX Root Placement.) .3.0. 6400004 oun} eee gb eH eee ao gh doe 


Linking Conflicts: . 4.0 cic toca ee eee cane be eeaw eka eedanended 
UNIX and OpenVMS File Specification Delimiters ............... 
Valid and Invalid UNIX and OpenVMS File Specifications ......... 
Feature Test Macros - Standards ............ 0.00. e eens 
C RTL Feature Logical Names.............. 000 eee eee 
Functions with Dual Implementations....................2005. 
Socket Routines with Dual Implementations .................... 
Functions Restricted to 32-Bit Pointers ........... 0.0.0.0. cee 
Callbacks that Pass Only 32-Bit Pointers ..................005. 
I/O Functions and Macros ......... 0.00. eee eee nes 


Optional Characters Between % (or %n$) and the Input Conversion 
SPCC’... a0 ove ay oe wha a beaver daa we eh tee eee eeae eg ae ee 


Conversion Specifiers for Formatted Input...................0.. 


Optional Characters Between % (or %n$) and the Output Conversion 
Speciler ss ..0.2cdecceae eed dcwad ccd whddead eiwe de aahe da dean 


Conversion Specifiers for Formatted Output ................005. 
Character, String, and Argument-List Functions ................ 
Character-Classification Functions.......... 0.0000. e ee eens 


Error- and Signal-Handling Functions..................20.000- 
The Error Code Symbolic Values ............ 000 cc eee eee nee 
HP © RIL Sigtials .4¢di5 os cv edges ee taeetaeetaades eetiadade s 


HP C RTL Signals and Corresponding OpenVMS VAX Exceptions 
VA ONLY)... saxcsat sae to TAS Teetep Gav cet Wi eI War: eRGoo xe Serena Ade hap Ve! Bi woe ele Ne ams Gad waar STs Hye! Ge 


HP C RTL Signals and Corresponding OpenVMS Alpha Exceptions 
ATMs OTL Via sa S Ga tee ide Bas Rend: SoG Siar we, MOLE a Ger IRE ag Bap Rs as Whe Tac Tl Wo AOE. a, She We HO ieee: GSO 


HP C RTL Signals and Corresponding OpenVMS I64 Exceptions 
(LOD OMY)! ss san dat Se wasasas acide tet Gan Re Giese pees Wwe Gockes Be area DaMIaY toy Hoos! Be se Medes Ib: Tar eds Hwee: wer Oe He dens 


Subprocess Functions. ........ 0.0... eee ees 
Curses Functions and Macros .......... 0.0.00 cece eee eee eee 


Memory Allocation Functions..........0 0.0.0.0 eee eee ees 
System Functions. ... 0.0.0.0... ee eee ees 
Locale Categories... 0... 0. eee eens 
Date/Time Functions ......... 20.0.0 ees 
Time-zone Filename Acronyms ............. 000 eee eens 
Symbolic Link Functions ......... 0.0.0... cece eee 
Interpretation of the mode Argument ............ 0.0000 cence 
File Protection Values and Their Meanings ...................5. 
RMS Valid Keywords and Values ............ 0000 c cece eee eee 


12-13 


1-10 
1-16 
1-16 
1-19 
1-29 
1-62 
1-63 
1-65 
1-65 

2-1 


XxiV 


CI DLPUCLUEES hfe s6 Golem HSH ow Ble ww Wa ee low lo WU Rod ORE Mew eS REF-372 


Optional Characters in strfmon Conversion Specifications.......... REF-615 
strfmon Conversion Specifiers ...... 0.0.0.0... cee eee REF-616 
Optional Elements of strftime Conversion Specifications ........... REF-619 
strftime Conversion Specifiers ... 0... 0.0.0.0. eee ees REF-619 
strptime Conversion Specifications........... 0.00. eee REF-633 
sysconf Argument and Return Values ............ 0.000 c eens REF-662 
Time-Zone Initialization Rules........... 0.0.0.0 ee eee REF-695 
The vfork and fork Functions...........0..0 0000: cee eee eee eee REF-721 
Optional Elements of wesftime Conversion Specifications .......... REF-761 
wesftime Conversion Specifiers .... 0... 0... eee eee REF-761 
Functions Available on All OpenVMS Systems .................4. A-1 
Functions Added in OpenVMS Version 6.2..............00-00005 A-3 
Functions Added in OpenVMS Version 7.0.............00000e eee A-4 
Functions Added in OpenVMS Alpha Version 7.0 ................ A-5 
Functions Added in OpenVMS Version 7.2............0000e ee eee A-6 
Functions Added in OpenVMS Version 7.3........... 00000 e ee eee A-6 
Functions Added in OpenVMS Version 7.3-1 ..............2.0005 A-6 
Functions Added in OpenVMS Version 7.3-2 ...........0000000 ee A-7 
Functions Added in OpenVMS Version 8.2.............00 00s eeee A-7 
Functions Added in OpenVMS Version 8.3............000 00 ee eee A-8 
Duplicated Prototypes .... 0.0.0... eee eee B-1 


Preface 


This manual describes the HP C Run-Time Library (RTL) for the OpenVMS 
operating system on VAX, Alpha, and Intel Itanium processors. HP OpenVMS 
Industry Standard 64 for Integrity Servers is the full product name of the 
OpenVMS operating system on Intel Itanium processors. The shortened forms, 
OpenVMS I64 and 164, are also used throughout this manual. 


This manual provides reference information about the C RTL functions and 
macros that perform input/output (I/O) operations, character and string 
manipulation, mathematical operations, error detection, subprocess creation, 
system access, screen management, and emulation of selected UNIX features. It 
also notes portability concerns between operating systems, where applicable. 


The HP C RTL contains XPG4-compliant internationalization support, providing 
functions to help you develop software that can run in different languages and 
cultures. 


The complete HP C Run-Time Library (C RTL) needed for use with the HP C and 
C++ compilers is distributed with the OpenVMS Alpha and 164 operating systems 
in both shared image and object module library form. 


This manual no longer documents the socket routines used for writing Internet 
application programs for the TCP/IP Services protocol. For help on the socket 
routines, use the following: 


$ HELP TCPIP Services Programming Interfaces Sockets API 
Also see the HP TCP/IP Services for OpenVMS product documentation. 


Intended Audience 
This manual is intended for experienced and novice programmers who need 
reference information on the functions and macros found in the HP C RTL. 
Document Structure 
This manual has the following chapters, reference section, and appendixes: 
e Chapter 1 provides an overview of the HP C RTL. 
e Chapter 2 discusses the Standard I/O, Terminal I/O, and UNIX I/O functions. 
e Chapter 3 describes the character, string, and argument-list functions. 
e Chapter 4 describes the error-handling and signal-handling functions. 
e Chapter 5 explains the functions used to create subprocesses. 
e Chapter 6 describes the Curses Screen Management functions. 
e Chapter 7 discusses the math functions. 


e Chapter 8 explains the memory allocation functions. 
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Chapter 9 describes the functions used to interact with the operating system. 


Chapter 10 gives an introduction to the facilities provided in the HP C 
environment on OpenVMS systems for developing international software. 


Chapter 11 describes the date/time functions. 
Chapter 12 describes symbolic links and POSIX pathname support. 
The Reference Section describes all the functions in the HP C RTL. 


Appendix A contains version-dependency tables that list the HP C RTL 
functions supported on different OpenVMS versions. 


Appendix B lists the function prototypes that are duplicated in more than one 
header file. 


Related Documents 


The following documents may be useful when programming in HP C for 
OpenVMS Systems: 
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HP C User’s Guide for OpenVMS Systems—For C programmers who need 
information on using HP C for OpenVMS Systems. 


HP C Language Reference Manual—Provides language reference information 
for HP C on HP systems. 


VAX C to HP C Migration Guide—To help OpenVMS VAX application 
programmers migrate from VAX C to HP C. 


HP C Installation Guide for OpenVMS VAX Systems—For OpenVMS system 
programmers who install the HP C software on VAX systems. 


HP C Installation Guide for OpenVMS Alpha Systems—For OpenVMS system 
programmers who install the HP C software on Alpha systems. 


OpenVMS Master Index—For programmers who need to work with the VAX 
and Alpha machine architectures or the OpenVMS system services. This 
index lists manuals that cover the individual topics concerning access to the 
OpenVMS operating system. 


HP TCP/IP Services for OpenVMS Sockets API and System Services 
Programming—For information on the socket routines used for writing 
Internet application programs for the HP TCP/IP Services for OpenVMS 
product or other implementations of the TCP/IP protocol. 


HP TCP/IP Services for OpenVMS Guide to IPv6—For information on HP 
TCP/IP Services for OpenVMS IPv6 features, how to install and configure 
IPv6 on your system, changes in the socket application programming interface 
(API), and how to port your applications to run in an IPv6 environment. 


X/Open Portability Guide, Issue 3—Documents what is commonly known as 
the XPG3 specification. 


X/Open CAE Specification System Interfaces and Headers, Issue 4— 
Documents what is commonly known as the XPG4 specification. 


X/Open CAE Specification, System Interfaces and Headers, Issue 4, Version 
2—Documents what is commonly known as XPG4 V2. 


X/Open CAE Specification, System Interfaces and Headers, Issue 5— 
Documents what is commonly known as the XPG5 specification. 


e Technical Standard. System Interfaces, Issue 6—Combined Open Group 
Technical Standard and JEEE standard. IEEE Std 1003.1-2001, sometimes 
known as XPG6. 


e Standard for Information Technology - Portable Operating System Interface 
(POSIX) - Part 1: System Application Program Interface (API)—Amendment 
2: Threads Extension [C Language/—Documents what is also known as 
POSIX 1003.1c-1995. 


e ISO/IEC 9945-2:1993 - Information Technology - Portable Operating System 
Interface (POSIX) - Part 2: Shell and Utilities—Documents what is also 
known as ISO POSIX-2. 


e ISO/IEC 9945-1:1990 - Information Technology - Portable Operating System 
Interface (POSIX) - Part 1: System Application Programming Interface (API) 
(C Language)—Documents what is also known as ISO POSIX-1. 


e ANSI/ISO/IEC 9899:1999 - Programming Languages - C—The C99 standard, 
published by ISO in December, 1999 and adopted as an ANSI standard in 
April, 2000. 


e ISO/IEC 9899:1990-1994 - Programming Languages - C, Amendment 1: 
Integrity—Documents what is also known as ISO C, Amendment 1. 


e ISO/IEC 9899:1990[1992] - Programming Languages - C—Documents what 
is also known as ISO C. The normative part is the same as X3.159-1989, 
American National Standard for Information Systems - Programming 
Language C, also known as ANSI C. 


For more information about HP OpenVMS products and services, access the HP 
Web site at the following location: 


http: //www.hp.com/go/openvms 


Reader’s Comments 


HP welcomes your comments on this manual. Please send comments to either of 
the following addresses: 


Internet openvmsdoc@hp.com 
Postal Mail Hewlett-Packard Company 
OSSG Documentation Group, ZKO3-4/U08 
110 Spit Brook Rd. 
Nashua, NH 03062-2698 
How to Order Additional Documentation 


For information about how to order additional documentation, visit the following 
Web site address: 


http://www. hp.com/go/openvms/doc/order 


Conventions Used in this Document 


Convention Meaning 
HP OpenVMS Industry The variant of the OpenVMS operating system that runs 
Standard 64 for Integrity on the Intel Itanium architecture. 


Servers, OpenVMS 164, 164 
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Convention Meaning 


OpenVMS systems Refers to the OpenVMS operating system on all supported 
platforms, unless otherwise specified. 

Return The symbol | Return| represents a single stroke of the 
Return key on a terminal. 

Ctrl/X The symbol Ctrl/X, where letter X represents a terminal 


control character, is generated by holding down the Ctrl 
key while pressing the key of the specified terminal 


character. 
switch statement Monospace type identifies language keywords and the 
int data type names of HP C functions and header files. Monospace 
fprintf function type is also used when referring to a specific variable 
<stdio.h> header file name used in an example. 
argl Italic type indicates a placeholder, such as an argument 
or parameter name, and the introduction of new terms. 
$ RUN CPROG [Return Interactive examples show user input in boldface type. 
float x; A vertical ellipsis indicates that not all of the text of a 


program or program output is illustrated. Only relevant 
material is shown in the example. 


x= 5; 

option, ... A horizontal ellipsis indicates that additional parameters, 
options, or values can be entered. A comma that precedes 
the ellipsis indicates that successive items must be 
separated by commas. 

[output-source, ... | Square brackets, in function synopses and a few other 
contexts, indicate that a syntactic element is optional. 
Square brackets are not optional, however, when 
used to delimit a directory name in an OpenVMS file 
specification or when used to delimit the dimensions of a 
multidimensional array in HP C source code. 

se-specifier ::= In syntax definitions, items appearing on separate lines 

auto are mutually exclusive alternatives. 

static 

extern 

register 

[a | b] Brackets surrounding two or more items separated by a 
vertical bar ( | ) indicate a choice; you must choose one of 
the two syntactic elements. 

A A delta symbol is used in some contexts to indicate a 


single ASCII space character. 


Platform Labels 


A platform is a combination of operating system and hardware that provides 
a distinct environment. This manual contains information applicable to the 
OpenVMS operating system running on VAX, Alpha, and Itanium processors. 


The information in this manual applies to all of these processors, except when 
specifically labeled as follows: 
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Label Explanation 


(Alpha only) Specific to an Alpha processor. 


(164 only) Specific to an Intel Itanium processor running the OpenVMS 
operating system. On this platform, the product name of the 
operating system is OpenVMS Industry Standard 64 (or its 
abbreviated forms, OpenVMS [64 or 164). 


(VAX only) Specific to a VAX processor. 
(Alpha, I64) Specific to 164 and Alpha processors. 


New and Changed Features - OpenVMS Version 8.3 


The following sections describe the C Run-Time Library (RTL) enhancements 
included in OpenVMS Version 8.3. These enhancements provide improved UNIX 
portability, standards compliance, and the flexibility of additional user-controlled 
feature selections. New C RTL functions are also included. 


Symbolic Link and POSIX-Compliant Pathname Support 
OpenVMS Version 8.3 and higher provides Open Group-compliant symbolic-link 


support and POSIX-compliant pathname support. This support is intended 
to help partners and customers who port UNIX and LINUX applications to 
OpenVMS or who use a UNIX style development environment to reduce the 
application development costs and complexity previously associated with such 
porting efforts. 


Although this support is present, it does not guarantee 100% compatibility of 
UNIX files on OpenVMS systems. There may be some cases where developers 
still need to make modifications to UNIX or LINUX applications when porting 
them to OpenVMS. 


The following OpenVMS features are provided to support symbolic links and 


POSIX pathname processing: 


The following Open Group compliant symbolic-link functions are added to the 
C Run-Time Library: 


symlink 
readlink 
unlink 
realpath 
lchown 
Istat 


Existing C RTL functions such as creat, open, delete, and remove, now 
behave in accordance with Open Group specifications for symbolic links. 


RMS allows the C RTL to implement the above-mentioned functions. 
RMS routines such as SYS$OPEN, SYS$CREATE, SYS$PARSE, and 
SYS$SEARCH now support symbolic links. 


The contents of symbolic links on OpenVMS are interpreted as POSIX 
pathnames when encountered during pathwalks and searches. POSIX 
pathnames are now supported in OpenVMS and are usable through C RTL 
and RMS interfaces. 


A new feature logical DECC$POSIX_COMPLIANT_PATHNAMES is added to 
the C RTL to indicate that an application is operating in a POSIX-compliant 
mode. 
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e The DCL command CREATE/SYMLINK is used to create a symbolic link. 
e The DCL command SET ROOT is provided to create the system POSIX root. 
e Two GNV utilities, mt and umnt, are provided to set mount points. 


e DCL commands and utilities are modified to behave appropriately when 
acting on and encountering symbolic links. 


e The TCP/IP Services for OpenVMS Network File System (NFS) client and 
server are enhanced to support symbolic links on ODS5 volumes. 


e Relevant GNV utilities such as 1n (which can create a symbolic link) and 1s 
(which can display the contents of a symbolic link) are updated to provide 
access to and management of symbolic links. 


For more information on symbolic links and POSIX pathname processing, see 
Chapter 12. 


Byte-Range Locking 


The C RTL supports byte-range file locking using the F_GETLK, F_SETLK, and 
F_SETLKW commands of the fcnt1 function, as defined in The Open Group 
Base Specifications Issue 6. The OpenVMS lock manager is used to implement 
this feature. Byte-range file locking is allowed across clusters. You can only use 
offsets that fit into 32-bit unsigned integers. For more information, see the fcnt1l 
function in this manual. 


New C RTL Functions 


In addition to the symbolic link functions listed in Symbolic Link and POSIX- 
Compliant Pathname Support, the following new functions based on The Open 
Group Base Specifications Issue 6 have been added to the C RTL: 


crypt 
setkey 
encrypt 
fchmod 


C RTL TCP/IP Header File Updates 


XXX 


The C RTL ships header files for users to call TCP/IP. These headers have had 
numerous problems, making some of them unusuable for anything beyond trivial 
TCP/IP programming. 


Previously, corrected headers have shipped with several releases of TCP/IP 

in their examples area. This enhancement to the C RTL now places those 
corrected headers in the C RTL header library (DECC$RTLDEF.TLB). For more 
information, see the C RTL section of the OpenVMS Version 8.3 Release Notes. 
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Introduction 


The ISO/ANSI C standard defines a library of functions, as well as related 
types and macros, to be provided with any implementation of ANSI C. The HP 
C Language Reference Manual describes the ANSI-conformant library features 
common to all HP C platforms. The HP C Run-Time Library Reference Manual 
for OpenVMS Systems provides a more detailed description of these routines and 
their use in the OpenVMS environment. It also documents additional header 
files, functions, types, and macros that are available on the OpenVMS system. 


All library functions are declared in a header file. To make the contents of a 
header file available to your program, include the header file with an #include 
preprocessor directive. For example: 


#include <stdlib.h> 


Each header file contains function prototypes for a set of related functions, and 
defines any types and macros needed for their use. 


To list the header files on OpenVMS Alpha or 164 systems, use the following 
commands: 


$ LIBRARY/LIST SYSSLIBRARY:SYS$STARLET C.TLB 

$ LIBRARY/LIST SYSSLIBRARY : DECCSRTLDEF.TLB 

$ DIR SYS$COMMON: [DECCSLIB.REFERENCE.DECCS$RTLDEF] *.H; 
$ DIR SYS$LIBRARY:*.H; 


The first command lists the text module form of the header files for the OpenVMS 
system interfaces. The second lists the text module form of the header files 

for the HP C language interface. The third lists *.H header files for the HP C 
language interfaces. The fourth lists *.H header files for layered products and 
other applications. 


Note 


The SYS$COMMON:[DECC$LIB.REFERENCE.DECC$RTLDEF] 
directory is only a reference area for your viewing. The compiler still 
looks in the *.TLB files for #include file searches. 


To list the header files on OpenVMS VAX systems, use the following commands: 


$ DIR ‘FSTRNLMN("DECCS$LIBRARY INCLUDE") ‘*.H; 
$ DIR DECCS$LIBRARY INCLUDE:*.H; 


On OpenVMS VAX systems, the following command might also find additional or 
duplicate header files: 


$ DIR SYS$LIBRARY:*.H; 


However, duplicate files (such as <stdio.h>) found in SYS$LIBRARY probably 
support the VAX C Version 3.2 environment and should not be used with HP C. 
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Function definitions themselves are not included in the header files, but are 
contained in the HP C Run-Time Library (RTL) shipped with the OpenVMS 
operating system. Before using the HP C RTL, you must be familiar with the 
following topics: 


e The linking process 

e The macro substitution process 

e The difference between function definitions and function calls 
e The format of valid file specifications 

e The OpenVMS-specific methods of input and output (I/O) 

e The HP C for OpenVMS extensions and nonstandard features 


A knowledge of all these topics is necessary to effectively use the HP C RTL. This 
chapter shows the connections between these topics and the HP C RTL. Read this 
chapter before any of the other chapters in this manual. 


The primary purpose of the HP C RTL is to provide a means for C programs to 
perform I/O operations; the C language itself has no facilities for reading and 
writing information. In addition to I/O support, the HP C RTL also provides a 
means to perform many other tasks. 


Chapters 2 through 11 describe the various tasks supported by the HP C RTL. 
The Reference Section alphabetically lists and describes all the functions and 
macros available to perform these tasks. 


1.1 Using the HP C Run-Time Library 
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Introduction 


When working with the HP C RTL, you must be aware of some implementation 
specifics. 


First, if you plan to use HP C RTL functions in your C programs, make sure that 
a function named main or a function that uses the main_program option exists in 
your program. For more information, see the HP C Language Reference Manual 

or the HP C User’s Guide for OpenVMS Systems. 


Second, the HP C RTL functions are executed at run time, but references to these 
functions are resolved at link time. When you link your program, the OpenVMS 
linker resolves all references to HP C RTL functions by searching any shareable 
code libraries or object code libraries specified on the LINK command line. 


You can use the HP C RTL as a shareable image or you can use the HP C RTL 
object libraries. 


When you use the HP C RTL as a shareable image, the code for the RTL resides 
in an image file in SYS$SHARE and is shared by all HP C programs. After 
execution, control returns to your program. This process has a number of 
advantages: 


e You reduce the size of a program’s executable image. 
e The program’s image takes up less disk space. 
e The program swaps in and out of memory faster due to decreased size. 


e With HP C and HP C++, you no longer need to define an options file when 
linking your program against the shareable image. Linking against the RTL 
shareable image is now much simpler than it was with VAX C. In fact, it is 
the default method of linking to the HP C RTL. 


When linking to the HP C RTL, you do not need to define any LNK$LIBRARY 
logicals. In fact, you should deassign LNK$LIBRARY because linking with the 
shareable image is more convenient than linking with the HP C RTL object 
libraries. 


See your OpenVMS, HP C, or HP C++ release notes for any supplemental 
information about linking with the HP C RTL. 


1.2 RTL Linking Options on Alpha and 164 Systems apne, 162 


The following sections describe several ways of linking HP C and HP C++ 
programs with the HP C RTL on OpenVMS Alpha and I64 systems. 


1.2.1. Linking with the Shareable Image 


Most linking needs should be satisfied by using the HP C RTL shareable image 
DECC$SHR.EXE in the ALPHA$LIBRARY (Alpha only) OY TAG4$LIBRARY (164 only) 
directory. 


The shareable images VAXCRTL.EXE and VAXCRTLG.EXE do 

not exist on OpenVMS Alpha and 164 systems. The only C RTL 

shareable image is ALPHA$LIBRARY:DECC$SHR.EXE (Alpha only) or 
IA64$LIBRARY:DECC$SHR.EXE (164 only) , which the linker automatically finds 
through IMAGELIB.OLB. 


The fact that VAXCRTL*.EXE does not exist on Alpha and I64 systems has the 
following ramifications: 


e You must change any existing VAX C link procedures to eliminate any 
references to the VAXCRTL*.EXE images. An explicit reference to 
DECC$SHR.EXE is unnecessary because IMAGELIB.OLB is searched 
automatically by the linker (see the OpenVMS Linker Utility Manual). 


e Because DECC$SHR.EXE exports only prefixed universal symbols (ones 
that begin with DECC$), to successfully link against it make sure you cause 
prefixing to occur for all HP C RTL entry points that you use. 


If you use only the HP C RTL functions defined in the ANSI C Standard, all 
entry points will be prefixed. 


If you use HP C RTL functions not defined in the ANSI C Standard, you must 
compile in one of two ways to ensure prefixing: 


— Compile with the /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES 
qualifier. 


— Compile with the /STANDARD=VAXC or /STANDARD=COMMON 
qualifier; you get /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES as the 
default. 


To link against the shareable image, use the LINK command. For example: 
$ LINK PROG1 


The linker automatically searches IMAGELIB.OLB to find DECC$SHR.EXE, and 
resolves all C RTL references. 
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1.2.2 Linking with the Object Libraries dipie ony) 
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The HP C RTL object libraries on OpenVMS Alpha systems are used solely for 
linking programs compiled without /PREFIX=ALL. Please note that these object 
libraries do not exist on OpenVMS I64 systems. 


On OpenVMS Alpha systems, the HP C RTL provides the following object 
libraries in the ALPHA$LIBRARY directory: 


e VAXCCURSE.OLB 
e VAXCRTLD.OLB 

e VAXCRTLT.OLB 

e VAXCRTL.OLB 

e VAXCRTLX.OLB 

e VAXCRTLDX.OLB 
e VAXCRTLTX.OLB 


The object library VAXCCURSE.OLB, which provides access to the Curses 
functions, contains unprefixed entry points that vector to the appropriate prefixed 
entry points. 


The object libraries VAXCRTL.OLB, VAXCRTLD.OLB, VAXCRTLT.OLB, 
VAXCRTLX.OLB, VAXCRTLDX.OLB, and VAXCRTLTX.OLB also contain 
unprefixed entry points that vector to the appropriate prefixed entry points, 
depending on the floating-point type specified by the object library used: 


e VAXCRTL.OLB contains all HP C RTL routine name entry points as well as 
VAX G-floating double-precision, floating-point entry points. 


e VAXCRTLD.OLB contains a limited support of VAX D-floating double- 
precision, floating-point entry points. 


e VAXCRTLT.OLB contains IEEE T-floating double-precision, floating-point 
entry points. 


e VAXCRTLX.OLB contains G_floating support and support for the 
/L_DOUBLE_SIZE=128 compiler qualifier. 


e VAXCRTLDX.OLB contains D_floating support and support for the 
/L_DOUBLE_SIZE=128 compiler qualifier. 


e VAXCRTLTX.OLB contains IEEE T_floating support and support for the 
/L_DOUBLE_SIZE=128 compiler qualifier. 


/L_DOUBLE_SIZE=128 is the default. 


On the LINK command, specify only one of the VAXCRTL*.OLB libraries and, if 
needed, the VAXCCURSE.OLB library. 


In the default mode of the compiler (/STANDARD=RELAXED_ANSI89) and 
also in strict ANSI C mode, all calls to ANSI C standard library routines 

are automatically prefixed with DECC$. With the /[NO]PREFIX_LIBRARY_ 
ENTRIES qualifier, you can change this to prefix all HP C RTL names with 
DECC$, or to not prefix any HP C RTL names. Other options are also available 
for this qualifer. See the /[NO]PREFIX_LIBRARY_ENTRIES qualifier in this 
chapter for more information. 


When linking with /NOSYSSHR, if calls to the HP C RTL routines are prefixed 
with DECC$, then the modules in STARLET.OLB are the only ones you need 
to link against. Since STARLET.OLB is automatically searched by the linker 
(unless the link qualifier /NOSYSLIB is used), all prefixed RTL external names 
are automatically resolved. 


If any calls to the HP C RTL routines are not prefixed, then you need to 
explicitly link against VAXCRTL.OLB, VAXCRTLD.OLB, VAXCRTLT.OLB 

(or VAXCRTLX.OLB, VAXCRTLDX.OLB, or VAXCRTLDX.OLB), or 
VAXCCURSE.OLB, depending on which floating-point types you need, or if you 
want Curses functions. If you are linking with /NOSYSSHR, prefixed HP C RTL 
entry points are resolved in STARLET.OLB. If you are linking with /SYSSHR (the 
default), prefixed HP C RTL entry points are resolved in DECC$SHR.EXE. 


1.2.3 Examples 


The following examples show several different ways you might want to link with 
the HP C RTL. See Figure 1-1 for a graphical summary of these examples. 


1. Most of the time, you just want to link against the shareable image: 


$ CC/PREFIX LIBRARY ENTRIES=ALL ENTRIES PROG1 
$ LINK PROG1 


The linker automatically searches IMAGELIB.OLB to find DECC$SHR.EXE. 


2. If you want to use just object libraries (to write privileged code or for ease 
of distribution, for example), use the /NOSYSSHR qualifier of the LINK 
command: 


$ CC/PREFIX LIBRARY ENTRIES=ALL ENTRIES PROG1 
$ LINK/NOSYSSHR PROG1 


Prefixed RTL symbol references in the user program are resolved in the HP C 
RTL object library contained in STARLET.OLB. 


Notes 


e When linking HP C programs against the HP C RTL object 
libraries using the /NOSYSSHR qualifier, applications that 
previously linked without undefined globals may result in 
undefined globals for the CMA$TIS symbols. To resolve these 
undefined globals, add the following line to your link options file: 


SYSSLIBRARY : STARLET . OLB/ LIBRARY / INCLUDE=CMASTIS 


e Ifa program linked with the /NOSYSSHR qualifier makes a call 
to a routine that resides in a dynamically activated image, and the 
routine returns a value indicating an unsuccessful status, errno 
is set to ENOSYS, and vaxcSerrno is set to C$_NOSYSSHR. 

The error message corresponding to C$_NOSYSSHR is "Linking 
/NOSYSSHR disables dynamic image activation." An example of 
this situation is a program linked with /NOSYSSHR that makes a 
call to a socket routine. 
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3. (Alpha only). On OpenVMS Alpha systems, when compiling with prefixing 
disabled, in order to use object libraries that provide alternate 
implementations of C RTL functions, you need to use the VAXC*.OLB 
object libraries. In this case, compile and link as follows: 


$ CC/NOPREFIX LIBRARY ENTRIES PROG1 
$ LINK PROG1, MYLIB/LIBRARY, ALPHASLIBRARY: VAXCRTLX.OLB/LIBRARY 


Unprefixed HP C RTL symbol references in the user program are resolved in 
MYLIB and in VAXCRTL.OLB. 


Prefixed HP C RTL symbol references in VAXCRTLX.OLB are resolved in 
DECC$SHR.EXE through IMAGELIB.OLB. 


In this same example, to get IEEE T-floating double-precision floating-point 
support, you might use the following compile and link commands: 


$ CC/NOPREFIX LIBRARY ENTRIES/FLOAT=IEEE FLOAT PROG1 
$ LINK PROG1, MYLIB/LIBRARY, ALPHASLIBRARY: VAXCRTLTX.OLB/LIBRARY 


4. (Alpha only). Combining examples 2 and 3, you might want to use just the object 
libraries (for writing privileged code or for ease of distribution) and use an 
object library that provides C RTL functions. In this case, compile and link 
as follows: 


$ CC/NOPREFIX LIBRARY ENTRIES PROG1 
$ LINK/NOSYSSHR PROG1, MYLIB/LIBRARY, ALPHASLIBRARY: VAXCRTLX.OLB/LIBRARY 


Prefixed HP C RTL symbol references in VAXCRTL.OLB are resolved in 
STARLET.OLB. 


Figure 1-1 Linking with the HP C RTL on OpenVMS Alpha and 164 Systems 


Example 1 Example 2 Example 3 Example 4 
Prog 
VAXCRTL*.OLB VAXCRTL*.OLB 
STARLET.OLB 
STARLET.OLB 
DECC$SHR.EXE 
DECC$SHR.EXE 
/PREFIX=ALL /PREFIX=ALL /NOPREFIX /NOPREFIX 
IMAGELIB.OLB STARLET.OLB IMAGELIB.OLB STARLET.OLB 
(DECC$SHR.EXE) (DECC$SHR.EXE) 
ZK-6045A-GE 


1.3 RTL Linking Options on VAX Systems «ax on) 


Both the VAX C RTL and the HP C RTL can coexist on your OpenVMS VAX 
system. The VAX C RTL supports existing VAX C applications. The HP C RTL 
supports ANSI-compliant HP C and HP C++, as well as other components of the 
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OpenVMS environment. The HP C RTL also provides a mechanism for thread 
safety and performance improvements. 


Applications developed with VAX C will continue to use the VAX C RTL. However, 
you can relink VAX C applications to use the HP C RTL instead. This lets you 
take advantage of the new features of the HP C RTL and solve potential 
interoperability problems in complex applications that incorporate both the 

VAX C RTL and the HP C RTL. Existing applications that are relinked to use 
the HP C RTL should be carefully tested for possible problems resulting from 
the differences in behavior between the VAX C RTL and the HP C RTL. See the 
applicable HP C release notes and OpenVMS release notes for more information. 


The following sections describe several ways of linking HP C programs with the 
HP C RTL and VAX C RTL on OpenVMS VAX systems. 


1.3.1 Linking with the HP C RTL 


The HP C RTL provides a new set of files with different names from the VAX C 
RTL files. If you want to link with the HP C RTL, you need to change your link 
procedures to use the new file names. The following sections describe linking 
with the HP C RTL files. 


1.3.1.1 Linking with the HP C RTL Shareable Images 


Most linking needs should be satisfied by using the HP C RTL shareable image 
DECC$SHR.EXE in the SYS$LIBRARY directory. Use this linking method for 
programs that are written entirely in HP C or HP C++ code; that is, with no 
VAX C object modules. 


Because DECC$SHR.EXE exports only prefixed universal symbols (ones that 
begin with DECC$), to successfully link against it make sure you cause prefixing 
to occur for all HP C RTL entry points. 


If you use only the HP C RTL functions defined in the ANSI C Standard, all entry 
points will be prefixed. 

If you use HP C RTL functions not defined in the ANSI C Standard, you must 
compile in one of two ways to ensure prefixing: 

e Compile with the /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES qualifier. 


e Compile with the /STANDARD=VAXC or /STANDARD=COMMON qualifier; 
you get /PREFIX_LIBRARY_ENTRIES=ALL_ENTRIES as the default. 


Then link against the shareable image using the LINK command. For example: 
$ LINK PROG1 


If you are using the VAX C compiler and you want to link with DECC$SHR.EXE, 
you must link to one of the following files: 


VAXC2DECC.EXE 
VAXCG2DECC.EXE 


You link with them as follows: 


$ LINK PROG1,TT:/OPTIONS 
SYSSLIBRARY : VAXC2DECC/SHARE 
Ctr/Z 


Use the G-floating version, VAXCG2DECC.EXH, if you compiled with the 
/G_FLOAT or /FLOAT=G_FLOAT qualifier. 
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1.3.1.2 Linking with or Providing Your Own Shareable Images 


Most linking needs for an application using a shareable image are handled by 
a straightforward link command, regardless of whether the shared image uses 
HP C, VAX C, or some other programming language. 


For example, assume that SHARE1.EXE is a shareable image linked with 
VAXCRTL.EXE. Also assume that your program, PROG1, is compiled with HP C 
and, therefore, references prefixed names for C RTL functions. You can then use 
the following commands: 


$ LINK PROG1, SYSSINPUT: /OPTIONS 
MYDISK: [TEXT] SHARE1.EXE/SHARE 


If PROG1 does not use prefixed names, the link could result in link conflicts. If 
this occurs, see Section 1.3.2. 


1.3.1.3 Linking with the HP C RTL Object Libraries 
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The HP C RTL object libraries are used primarily for linking with the 
/NOSYSSHR qualifier. 


On OpenVMS VAX systems, the HP C RTL provides the following object libraries 
in the SYS$LIBRARY directory: 


e DECCCURSE.OLB 
e DECCRTLG.OLB 
e DECCRTL.OLB 


As with VAX C, if you specify more than one object library on the LINK command, 
you must do so in the order listed. 


You use these object libraries in the same way that you would use the VAX C RTL 
object libraries VAXCRTL.OLB, VAXCRTLG.OLB, and VAXCCURSE.OLB. For 
example: 


$ ! Link a D-float program 

$ LINK PROG1, SYS$LIBRARY:DECCRTL.OLB/LIBRARY 

$ | 

$ ! Link a G-float program 

$ LINK PROG2, SYS$LIBRARY:DECCRTLG.OLB/LIBRARY, - 
_$ SYS$LIBRARY: DECCRTL.OLB/LIBRARY 

$ | 
$ ! Link a D-float, Curses program 

$ LINK PROG1, SYS$LIBRARY:DECCCURSE.OLB/LIBRARY, - 
_$ SYS$LIBRARY: DECCRTL.OLB/LIBRARY 


Note 


When linking to the HP C RTL object libraries, you do not need to define 
any LNK$LIBRARY logicals. In fact, you must deassign LNK$LIBRARY 
when linking with the .OLB libraries; otherwise, you might see "multiply 
defined symbols" errors. 


In general, you should deassign LNK$LIBRARY because pointing 
this logical to the HP C RTL object libraries interferes with VAX C 
development. 


1.3.1.4 Linking with the HP C RTL Object Libraries /NOSYSSHR 


If you want to link your program with the HP C RTL object libraries using 
the /NOSYSSHR qualifier, you must specify /INCLUDE=CMASTIS for the 
object library. For OpenVMS VAX Version 7.3 and higher, you must specify 
/INCLUDE=(CMA$TIS,CMA$TIS_VEC). Otherwise, several symbols will be 
undefined and the resulting image will not execute. 


In order to add this qualifier, you cannot use the LNK$LIBRARY logicals to link 
with the HP C RTL. You must use a linker options file or list the HP C RTL 
object library on the command line. For example: 


$ LINK/NOSYSSHR PROG1, SYS$LIBRARY:DECCRTL.OLB/LIBRARY/INCLUDE=CMASTIS 


S$ LINK/NOSYSSHR PROG1, SYSSLIBRARY:DECCRTL.OLB - 
_$ /LIBRARY/INCLUDE=(CMAS$TIS,CMAS$TIS VEC) (OpenVMS V7.3 and higher) 


Notes 


e When linking HP C programs against the HP C RTL object libraries 
using the /NOSYSSHR qualifier, applications that previously linked 
without undefined globals may result in undefined globals for the 
CMAS$TIS symbols. To resolve these undefined globals, add the 
following line to your link options file: 


SYSSLIBRARY : STARLET .OLB/ LIBRARY /INCLUDE=CMASTIS 


SYSSLIBRARY : STARLET .OLB/LIBRARY/ INCLUDE= (CMASTIS, CMASTIS VEC) 
(OpenVMS V7.3 and higher) 


e Ifa program linked with the /NOSYSSHR qualifier makes a call 
to a routine that resides in a dynamically activated image, and the 
routine returns a value indicating an unsuccessful status, errno is 
set to ENOSYS, and vaxc$errno is set to C$_NOSYSSHR. The error 
message corresponding to C$_NOSYSSHR is "Linking /NOSYSSHR 
disables dynamic image activation." An example of this situation is 
a program linked with /NOSYSSHR that makes a call to a socket 
routine. 


1.3.2 Resolving Link-Time Conflicts with Multiple C RTLs 


This section describes the use of interoperability tools to resolve link-time 
conflicts when using multiple C RTLs. 


When migrating to the HP C RTL, multiple C RTLs will likely be needed to link 
an application. One C RTL might be explicitly linked against. A second C RTL 
might not be explicitly linked against, but brought into the link by means of a 
shareable image. For example, when developing a Motif program using HP C, the 
application must be linked against the HP C RTL and against the Motif images. 
Motif currently brings the VAX C RTL into the link. 


Problems encountered when linking with multiple C RTLs are a result of the 
OpenVMS linker resolving symbol references in the image being linked by 
searching the transitive closure of shareable images and libraries. That is, when 
linking with a shareable image, the linker searches that shareable image and 
all shareable images referenced in that shareable image. So when linking with 
VAXCRTL.EXE and with an image linked with VAXCRTLG.EXH, the linker 
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will find two instances of all the C RTL symbols (one in VAXCRTL and one in 
VAXCRTLG), and report a conflict. 


The object libraries do not conflict with routine names, but do conflict with the 
global symbols. Because VAX C implements global symbols as global overlaid 
psects, the linker attempts to connect all the instances of a C-generated psect 
with the same name. For example, a reference to stdin in the user program 

is connected with the psect of the same name in VAXCRTL.OLB. However, a 
shareable image that was linked with VAXCRTL.OLB also has a psect of the 
same name; this results in an error because the linker cannot connect those two 
definitions of the psect stdin. 


Three interoperability tools are provided with the HP C compiler and in a 
separate HP C/C++ RTL Run-Time Components kit to resolve link-time conflicts: 


e VAXC$LCL.OPT 
e VAXC$EMPTY.EXE 
¢ DECC$EMPTY.EXE 


These tools work by hiding the conflicting symbols from one of the C RTLs being 
linked. Which tool is required depends on what C RTLs are used by the main 
application and the shareable image. 


Table 1-1 shows typical C RTL conflicts and the interoperability tool required 
to resolve it. In the table, VAXCRTL.EXE refers to either VAXCRTL.EXE or 
VAXCRTLG.EXE. 


Table 1-1 Linking Conflicts 


Linker Message Type of Conflict Tool Needed 
LINK-E-MULSHRPSC VAXCRTL.OLB/VAXCRTL.EXE VAXC$LCL.OPT 
LINK-E-SHRPSCLNG VAXCRTL.OLB/DECCRTL.OLB VAXC$LCL.OPT 
LINK-E-MULSHRPSC, DECCRTL.OLB/VAXCRTL.EXE VAXC$LCL.OPT 
LINK-E-SHRPSCLNG 

None DECCRTL.OLB/DECC$SHR.EXE DECC$EMPTY 
LINK-W-MULDEF VAXCRTL.EXE/VAXCRTLG.EXE VAXC$EMPTY 
LINK-W-MULDEF VAXC2DECC.EXE/VAXCRTL.EXE VAXC$EMPTY 


1.3.2.1 Using VAXC$LCL.OPT 
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VAXC$LCL.OPT is required when building any shareable image linked with the 
VAX C RTL object library or HP C RTL object library. 


If the shareable image is built without using VAXC$LCL.OPT, the C RTL global 
symbols are visible in the shareable image and cause linker conflicts when users 
of the image link against it. For example: 


SLINK-E-MULSHRPSC, psect CSSTRNS_ VALUES defined in 
shareable image IMAGE1.EXE; is multiply defined in 
shareable image SYSSLIBRARY:VAXCRTL.EXE;1 

-LINK-E-NOIMGFIL, image file not created 


In this example, the shareable image IMAGE1 uses VAXCRTL.OLB, and the 
image being linked uses VAXCRTL.EXE. For a successful link, relink the 
shareable image using VAXC$LCL.OPT: 
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$ LINK/SHARE IMAGE1.O0BJ, IMAGE1.OPT/OPTIONS, SYS$LIBRARY:VAXCRTL/LIBRARY, - 
_$ SYS$LIBRARY: VAXCSLCL.OPT/OPTIONS 


The following message also indicates a conflict involving the VAX C RTL object 
library: 


SLINK-E-SHRPSCLNG, Psect STDIN has length of 8 
in module CSEXTERNDATA file SYSSLIBRARY:DECCRTL.OLB; 2 
which exceeds length of 4 in shareable image IMAGE1.EXE; 
-LINK-E-NOIMGFIL, image file not created 


In this example, the shareable image IMAGE1 uses VAXCRTL.OLB, and the 
image being linked uses DECCRTL.OLB. For a successful link, relink the 
shareable image using VAXC$LCL.OPT. 


If the shareable image cannot be relinked (as in the case of a third-party 
shareable image), then the interoperability tool can be applied to the main 
image. If the main image is being linked against DECCRTL.OLB, then apply 
VAXC$LCL.OPT to the link of the main image. 


If the main image is being linked against VAXCRTL.EXE, the only solution is to 
get the shareable image fixed, because applying any of the interoperability tools 
to the link of the main image will result in an unsuccessful link. 


1.3.2.2 Using VAXCSEMPTY.EXE 


Use VAXC$EMPTY.EXE to link a main application with both VAXC2DECC.EXE 
(or VAXCG2DECC.EXE) and a shareable image linked with VAXCRTL.EXE (or 
VAXCRTLG.EXE). Using VAXC$EMPTY.EXE hides all the global symbols in the 
VAXCRTL*.EXE shareable image to prevent conflicts with VAXC2DECC.EXE or 
VAXCG2DECC.EXE. 


Also use VAXC$EMPTY.EXE to link an application with both VAXCRTL.EXE and 
a shareable image linked with VAXCRTLG.EXE (or vice versa). 


When there is a conflict between C RTL shareable images, the linker produces 
large numbers of messages similar to the following: 


SLINK-W-MULDEF, symbol ACOS multiply defined 
in module VAXCRTL file SYSSCOMMON: [SYSLIB] VAXCRTL.EXE;18 


In this example, the shareable image is linked with VAXCRTL.EXE, and the 
main program is linked with VAXC2DECC.EXE. 


The solution is to define the VAXCRTL logical to point to VAXC$EMPTY.EXE 
before linking the main program: 


$ DEFINE/USER VAXCRTL SYS$LIBRARY: VAXCSEMPTY . EXE 

$ LINK/EXEC=MAIN IMAGE MAIN PROG, OBJ1,0BJ2,...,SYS$INPUT: /OPTIONS 
IMAGE1/SHARE 

VAXCRTL/SHARE 

Ctr/Z 


Note the following about this solution: 


e Your linker options file cannot reference SYS$LIBRARY:VAXCRTL; it must 
reference only VAXCRTL. 


¢ Do not link explicitly against VAXC$EMPTY.EXE or your application will 
neither link nor run correctly. 


¢ Do not leave the VAXCRTL pointing to VAXC$EMPTY.EXE or your 
application will not run correctly. 


Introduction 1-11 


e The DEFINE/USER command is used to ensure that the logical definition is 
removed after execution of the LINK command. Make sure that no commands 
intervene between the DEFINE/USER command and the LINK command. 


Follow the same process when linking against VAXCRTLG.EXE by defining the 
VAXCRTLG logical to point to VAXC$EMPTY.EXE. 


1.3.2.3. Using DECCS$EMPTY.EXE 


The DECC$EMPTY.EXE interoperability tool allows a program to use the HP C 
object library even when the program links with a shareable image that was 
linked with DECC$SHR.EXE. 


If DECC$EMPTY.EXE is not used during the link, all HP C RTL references from 
the main program will be resolved in DECC$SHR.EXE, not in the object library. 
There is no linker message that indicates this fact. 


For example, if IMAGE1 is linked against DECC$SHR, and the following link is 
performed, then the main image will not contain any HP C RTL object modules. 
All C RTL references from the main progam are resolved in DECC$SHR: 


$ LINK/EXEC=MAIN IMAGE MAIN PROG,OBJ1,...,SYSS$INPUT: /OPTIONS 
IMAGE1/SHARE 

SYSSLIBRARY : DECCRTL/LIBRARY 

Ctri/Z 


By defining the DECC$SHR logical to point to DECC$EMPTY.EXE immediately 
before the link, all references to C RTL symbols from the main program are 
resolved in the HP C RTL object library. For example: 


$ DEFINE/USER DECCSSHR SYSSLIBRARY:DECCSEMPTY.EXE 

$ LINK/EXEC=MAIN IMAGE MAIN PROG, OBJ1,...,SYSS$INPUT: /OPTIONS 
IMAGE1/SHARE 

SYSSLIBRARY : DECCRTL/LIBRARY 


Note the following about this solution: 


¢ Do not link explicitly against DECC$EMPTY.EXE or your application will 
neither link correctly nor run correctly. 


¢ Do not leave the DECC$SHR logical pointing to DECC$EMPTY.EXE or your 
application will not run correctly. 


e The DEFINE/USER command is used to ensure that the logical definition is 
removed after execution of the LINK command. Make sure that no commands 
intervene between the DEFINE/USER command and the LINK command. 


1.3.3 Linking Examples for HP C or HP C++ Code Only 


The following examples show the different ways you might want to link HP C 
only or HP C++ only programs with the HP C RTL on OpenVMS VAX systems: 


1. Most of the time, you just want to link against the shareable image: 


$ CC/DECC/PREFIX LIBRARY ENTRIES=ALL ENTRIES PROG1 
$ LINK PROG1 


The linker automatically searches IMAGELIB.OLB to find DECC$SHR.EXE. 


2. If you want to use just object libraries (to write privileged code or for ease 
of distribution, for example), use the /NOSYSSHR qualifier of the LINK 
command: 


1-12 Introduction 


$ CC/DECC/PREFIX LIBRARY ENTRIES=ALL ENTRIES PROG1 
$ LINK/NOSYSSHR PROG1, SYS$LIBRARY:DECCRTL.OLB/LIBRARY/INCL=CMASTIS 


$ LINK/NOSYSSHR PROG1, SYSS$LIBRARY:DECCRTL.OLB - 
_$ /LIBRARY/INCL=(CMAS$TIS,CMASTIS VEC) (OpenVMS V7.3 and _ higher) 


Prefixed HP C RTL symbol references in the user program are resolved in 
STARLET.OLB. 


3. When compiling with prefixing disabled, in order to use object libraries that 
provide alternate implementations of C RTL functions, you need to use the 
DECC*.OLB object libraries. In this case, compile and link as follows: 


$ CC/DECC/NOPREFIX LIBRARY ENTRIES PROG1 
$ LINK PROG1, MYLIB/LIBRARY, - 
_$ SYS$LIBRARY: DECCRTL.OLB/LIBRARY 


Unprefixed HP C RTL symbol references in the user program are resolved in 
MYLIB and DECCRTL.OLB. The unprefixed names reference prefixed names 
resolved in DECC$SHR.EXE. 


You can link with any valid combination of DECCRTL.OLB, 
DECCRTLG.OLB, and DECCCURSE.OLB. In this same example, to get 
G-floating double-precision, floating-point support, use the following compile 
and LINK commands: 


$ CC/DECC/NOPREFIX LIBRARY ENTRIES/FLOAT=G FLOAT PROG1 
$ LINK PROG1, MYLIB/LIBRARY, SYS$LIBRARY:DECCRTLG.OLB/LIBRARY, - 
_$ SYS$LIBRARY: DECCRTL.OLB/LIBRARY 


4. Combining examples 2 and 3, you might want to use just the object libraries 
(for writing privileged code or for ease of distribution) and use an object 
library that provides C RTL functions. In this case, compile and link as 
follows: 


$ CC/DECC/NOPREFIX LIBRARY ENTRIES PROG1 
$ LINK/NOSYSSHR PROG1, MYLIB/LIBRARY, - 
_$ SYS$LIBRARY: DECCRTL.OLB/LIBRARY 


1.3.4 Linking Examples for VAX C and HP C Code Combined 


You might have programs that combine VAX C and HP C (or HP C++) code. The 
following examples show different ways to link such programs with the HP C 
RTL on OpenVMS VAX systems. These examples correspond to the examples in 
Section 1.3.3. 


1. To link against the shareable image, specify the VAXC2DECC.EXE shareable 
image: 


$ CC/DECC PROG1 
$ CC/VAXC PROG2 
$ LINK PROG1, PROG2, TT:/OPTIONS 
SYSS$LIBRARY : VAXC2DECC.EXE/SHARE 
Ctri/Z 


Prefixed C RTL calls from PROG1 are resolved in DECC$SHR. Unprefixed 


C RTL calls from PROG2 are resolved in VAXC2DECC.EXE, which transfers 
them to DECC$SHR. 


2. If you want to use just object libraries (to write privileged code or for ease 
of distribution, for example), use the /NOSYSSHR qualifier of the LINK 
command: 
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$ CC/DECC PROG1 
$ CC/VAXC PROG2 
$ LINK/NOSYSSHR PROG1, PROG2, SYSS$LIBRARY:DECCRTL.OLB/LIBRARY/INCL=CMASTIS 


All C RTL calls from both PROG1 and PROG2 are resolved in 
DECCRTL.OLB. 


3. When compiling with prefixing disabled, in order to use object libraries that 
provide alternate implementations of C RTL functions, you need to use the 
DECC*.OLB object libraries. In this case, compile and link as follows: 


$ CC/DECC/NOPREFIX LIBRARY ENTRIES PROG1 

$ CC/VAXC PROG2 

$ LINK PROG1, PROG2, MYLIB/LIBRARY, - 
_SSYS$LIBRARY : DECCRTL.OLB/LIBRARY/INCL=CMAS$TIS 


Unprefixed HP C RTL symbol references in the user program are resolved in 
MYLIB and DECCRTL.OLB. 


4. Combining examples 2 and 3, you might want to use just the object libraries 
(for writing privileged code or for ease of distribution) and use an object 
library that provides C RTL functions. In this case, compile and link as 
follows: 


$ CC/DECC/NOPREFIX LIBRARY ENTRIES PROG1 

$ CC/VAXC PROG2 

$ LINK/NOSYSSHR PROG1, PROG2, MYLIB/LIBRARY, - 
_§ SYS$LIBRARY:DECCRTL.OLB/LIBRARY /INCL=CMAS$TIS 


1.3.5 Linking with the VAX C RTL /NOSYSSHR 


This section applies to programs running on OpenVMS VAX Version 6.0 or higher. 


For programs that currently link with the VAX C RTL object libraries using 

the /NOSYSSHR qualifier, you must specify /INCLUDE=CMAS$TIS for the object 
library. Otherwise, several symbols will be undefined and the resulting image will 
not execute. In order to add this qualifier, you cannot use the LNK$LIBRARY 
logicals to link with the VAX C RTL object libraries. You must use a linker 
options file or list the VAX C RTL object libraries on the command line. For 
example: 


$ LINK/NOSYSSHR PROG1, SYS$LIBRARY:VAXCRTL.OLB/LIBRARY/INCLUDE=CMASTIS 


1.4 HP C RTL Function Prototypes and Syntax 


After learning how to link object modules and include header files, you must 
learn how to reference HP C functions in your program. The remaining chapters 
in this manual provide detailed descriptions of the HP C RTL functions. 


1.4.1 Function Prototypes 
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In all chapters, the syntax describing each function follows the standard 
convention for defining a function. This syntax is called a function prototype 
(or just prototype). The prototype is a compact representation of the order of a 
function’s arguments (if any), the types of the arguments, and the type of the 
value returned by a function. We recommend the use of prototypes. 


If the return value of the function cannot be easily represented by a C data-type 
keyword, look for a description of the return values in the explanatory text. The 
prototype descriptions provide insight into the functionality of the function. These 
descriptions may not describe how to call the function in your source code. 
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For example, consider the prototype for the feof function: 


#include <stdio.h> 
int feof(FILE “file_ptr); 


This syntax shows the following information: 


e The feof prototype resides in the <stdio.h> header file. To use feof, you 
must include this header file. (Declaring HP C RTL functions yourself is not 
recommended.) 


e The feof function returns a value of data type int. 


e There is one argument, file_ptr, that is of type "pointer to FILE". FILE is 
defined in the <stdio.h> header file. 


To use feof in a program, include <stdio.h> anywhere before the function call to 
feof, as in the following example: 


#include <stdio.h> /* Include Standard 1/0 */ 


main () 


FILE *infile; /* Define a file pointer */ 


‘ /* Call the function feof */ 
while ( ! feof(infile) ) /* Until EOF reached */ 
/* Perform file operations */ 


} 
1.4.2 Syntax Conventions for Function Prototypes 


Since some library functions take a varying number of parameters, syntax 
descriptions for function prototypes adhere to the following conventions: 


e Ellipses (... ) are used to indicate a varying number of parameters. 


e In cases where the type of a parameter may vary, its type is not shown in the 
syntax. 


Consider the printf syntax description: 


#include <stdio.h> 
int printf(const char *format_specification, . .. ); 


The syntax description for printf shows that you can specify one or more optional 
parameters. The remaining information about printf parameters is in the 
description of the function. 


1.4.3 UNIX Style File Specifications 


The HP C RTL functions and macros often manipulate files. One of the 

major portability problems is the different file specifications used on various 
systems. Since many C applications are ported to and from UNIX systems, it is 
convenient for all compilers to be able to read and understand UNIX system file 
specifications. 
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The following file specification conversion functions are included in the HP C RTL 
to assist in porting C programs from UNIX systems to OpenVMS systems: 


— decc$match_wild 

— deccStranslate_vms 
— deccSfix time 

— deccSto vms 

— deccSfrom_vms 


The advantage of including these file specification conversion functions in the 
HP C RTL is that you do not have to rewrite C programs containing UNIX 
system file specifications. HP C can translate most valid UNIX system file 
specifications to OpenVMS file specifications. 


Please note the differences between the UNIX system and OpenVMS file 
specifications, as well as the method used by the RTL to access files. For 
example, the RTL accepts a valid OpenVMS specification and most valid 

UNIX file specifications, but the RTL cannot accept a combination of both. 

Table 1-2 shows the differences between UNIX system and OpenVMS system file 
specification delimiters. 


Table 1-2. UNIX and OpenVMS File Specification Delimiters 


OpenVMS 

Description System UNIX System 
Node delimiter of / 

Device delimiter : / 

Directory path delimiter [|] / 

Subdirectory delimiter Led / 

File extension delimiter : 

File version delimiter : Not applicable 


For example, Table 1-3 shows the formats of two valid specifications and one 
invalid specification. 


Table 1-3 Valid and Invalid UNIX and OpenVMS File Specifications 


System File Specification Valid/Invalid 

OpenVMS BEATLE::DBAO:[MCCARTNEY]SONGS.LIS Valid 

UNIX beatle!/usr1/mccartney/songs.lis Valid 

— BEATLE::DBAO:[MCCARTNEY.C] Invalid 
/songs.lis 


When HP C translates file specifications, it looks for both OpenVMS and UNIX 
system file specifications. Consequently, there may be differences between how 
HP C translates UNIX system file specifications and how UNIX systems translate 
the same UNIX file specification. 
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For example, if the two methods of file specification are combined, as in 
Table 1-8, HP C RTL can interpret [MCCARTNEY.C]/songs.lis as either 
[IMCCARTNEY]songs.lis or [C]songs.lis. Therefore, when HP C encounters a 
mixed file specification, an error occurs. 


UNIX systems use the same delimiter for the device name, the directory names, 
and the file name. Due to the ambiguity of UNIX file specifications, HP C 

may not translate a valid UNIX system file specification according to your 
expectations. 


For instance, the OpenVMS system equivalent of /bin/today can be either 
[BIN]TODAY or [BIN.TODAY]. HP C can make the correct interpretation only 
from the files present. If a file specification conforms to UNIX system file name 
syntax for a single file or directory, it is converted to the equivalent OpenVMS file 
name if one of the following conditions is true: 


e Ifthe specification corresponds to an existing OpenVMS directory, it is 
converted to that directory name. For example, /dev/dir/sub is converted to 
DEV:[DIR.SUB] if DEV:[DIR.SUB] exists. 


e Ifthe specification corresponds to an existing OpenVMS file name, it is 
converted to that file name. For example, /dev/dir/file is converted to 
DEV: [DIR] FILE if DEV:[DIR]FILE exists. 


e If the specification corresponds to a nonexistent OpenVMS file name, but the 
given device and directory exist, it is converted to a file name. For example, 
/dev/dir/file is converted to DEV:[DIR]FILE if DEV:[DIR] exists. 


Note 


Beginning with OpenVMS Version 7.3, you can instruct the HP C RTL 
to interpret the leading part of a UNIX style file specification as either a 
subdirectory name or a device name. 


As with previous releases, the default translation of foo/bar (UNIX style 
name) is FOO:BAR (OpenVMS style device name). 


To request translation of foo/bar (UNIX style name) to [.FOO]BAR 
(OpenVMS style subdirectory name), define the logical name 
DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION to ENABLE. 
DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION is checked 
only once per image activation, not on a file-by-file basis. Defining this 
logical affects not only the decc$to_vms function, but all HP C RTL 
functions that accept both UNIX style and OpenVMS style file names as 
an argument. 


In the UNIX system environment, you reference files with a numeric file 
descriptor. Some file descriptors reference Standard I/O devices; some descriptors 
reference actual files. If the file descriptor belongs to an unopened file, the HP C 
RTL opens the file. HP C equates file descriptors with the following OpenVMS 
logical names: 
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File Descriptor OpenVMS Logical Meaning 


0 SYS$INPUT Standard input 
1 SYS$OUTPUT Standard output 
2 SYS$ERROR Standard error 


1.4.4 Extended File Specifications 


The ODS-5 volume structure provides enhanced support for mixed UNIX and 
OpenVMS style file names. It supports long file names, allows the use of a wider 
range of characters within file names, and preserves case within file names. With 
OpenVMS Alpha Version 7.3-1, the C RTL has greatly improved support of ODS-5 
characters, with 250 of the 256 characters supported, as opposed to only 214 
supported previously. Also, file names without file types can now be accessed. 


To enable the new support, you must define one or more C RTL feature logical 
names. These names include the following: 


DECC$EFS_CHARSET 
DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION 
DECC$FILENAME_UNIX_NO_VERSION 
DECC$FILENAME_UNIX_REPORT 
DECC$READDIR_DROPDOTNOTYPE 
DECC$RENAME_NO_INHERIT 


See Section 1.6 for more information on these and other feature logical names. 


1.4.5 Symbolic Links and POSIX Pathnames 


OpenVMS provides support for Open Group compliant symbolic links and POSIX 
pathname processing. See Chapter 12 for more information. 


1.5 Feature-Test Macros for Header-File Control 


Feature-test macros provide a means for writing portable programs. They ensure 
that the HP C RTL symbolic names used by a program do not clash with the 
symbolic names supplied by the implementation. 


The HP C RTL header files are coded to support the use of a number of feature- 
test macros. When an application defines a feature-test macro, the HP C RTL 
header files supply the symbols and prototypes defined by that feature-test macro 
and nothing else. If a program does not define such a macro, the HP C RTL 
header files define symbols without restriction. 


The feature-test macros supported by the HP C RTL fall into the following broad 
categories for controlling the visibility of symbols in header files according to the 
following: 


e Standards 
e Multiple-version support 


e Compatibility 
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1.5.1 Standards Macros 
The HP C RTL implements parts of the following standards: 


X/Open CAE Specification, System Interfaces and Headers, Issue 4, Version 2, 
also known as XPG4 V2. 


X/Open CAE Specification, System Interfaces and Headers, Issue 4, also 
known as XPG4. 


Standard for Information Technology - Portable Operating System Interface 
(POSIX) - Part 1: System Application Program Interface (API)—Amendment 
2: Threads Extension [C Language], also known as POSIX 1003.1c-1995 or 
IEEE 1003.1c-1995. 


ISO/IEC 9945-2:1993 - Information Technology - Portable Operating System 
Interface (POSIX) - Part 2: Shell and Utilities, also known as ISO POSIX-2. 


ISO/IEC 9945-1:1990 - Information Technology - Portable Operating System 
Interface (POSIX) - Part 1: System Application Programming Interface (API) 
(C Language), also known as ISO POSIX-1. 


ANSI/ISO/IEC 9899:1999 - The C99 standard, published by ISO in December, 
1999 and adopted as an ANSI standard in April, 2000. 


ISO/IEC 9899:1990-1994 - Programming Languages - C, Amendment 1: 
Integrity, also known as ISO C, Amendment 1. 


ISO/IEC 9899:1990 - Programming Languages - C, also known as ISO C. The 
normative part is the same as X3.159-1989, American National Standard for 
Information Systems - Programming Language C, also known as ANSI C. 


1.5.2 Selecting a Standard 


You can define a feature-test macro to select each standard. You can do this 
either with a #define preprocessor directive in your C source before the inclusion 
of any header file, or with the /DEFINE qualifier on the CC command line. 


Table 1—4 lists and describes the HP C RTL feature-test macros that control 
standards support. 


Table 1-4 Feature Test Macros - Standards 


Other 
Standard Standards 
Macro Name Selected Implied Description 
_XOPEN_SOURCE_ XPG4 V2 XPG4, Makes visible XPG4-extended features, 
EXTENDED ISO POSIX-2, including traditional UNIX based 


ISO POSIX-1, interfaces not previously adopted by 
ANSI C X/Open. 


(continued on next page) 
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Table 1-4 (Cont.) Feature Test Macros - Standards 


Other 
Standard Standards 
Macro Name Selected Implied Description 
_XOPEN_SOURCE XPG4 (X ISO POSIX-2,. Makes visible XPG4 standard symbols 
/Open Issue ISO POSIX-1, and causes _POSIX_C_SOURCE to be 
4) ANSI C set to 2 if it is not already defined with 
a value greater than 2.' ” 
_XOPEN_SOURCE=500 X/Open Issue ISO POSIX-2, Makes visible X/Open Issue 5 standard 
5 ISO POSIX-1, | symbols and causes _POSIX_C_ 
ANSI C SOURCE to be set to 2 if it is not 
already defined with a value greater 
than 2? 
_XOPEN_SOURCE=600 X/Open Issue ISO POSIX-2, Makes visible X/Open Issue 6 standard 
6 ISO POSIX-1, symbols and causes _POSIX_C_ 
ANSI C SOURCE to be set to 2 if it is not 
already defined with a value greater 
than 2.1? 
_POSIX_C_SOURCE==199506 IEEE ISO POSIX-2, Header files defined by ANSI C make 
1003.1c-1995 ISO POSIX-1, visible those symbols required by IEEE 
ANSI C 1003.1c-1995. 
_POSIX_C_SOURCE= =2 ISO POSIX-2 ISO POSIX-1, Header files defined by ANSI C make 
ANSI C visible those symbols required by ISO 
POSIX-2 plus those required by ISO 
POSIX-1. 
_POSIX_C_SOURCE= = ISO POSIX-1 ANSI C Header files defined by ANSI C make 
visible those symbols required by ISO 
POSIX-1. 
__STDC_VERSION__==199409 ISOC amdt ANSIC Makes ISO C Amendment 1 symbols 
1 visible. 
_ANSI_C_SOURCE ANSI C — Makes ANSI C standard symbols 
visible. 
lWhere the ISO C Amendment 1 includes symbols not specified by XPG4, defining __STDC_VERSION__ == 199409 and 


_XOPEN_SOURCE (or _XOPEN_SOURCE_EXTENDED) selects both ISO C and XPG4 APIs. Conflicts that arise when 
compiling with both XPG4 and ISO C Amendment 1 resolve in favor of ISO C Amendment 1. 


2Where XPG4 extends the ISO C Amendment 1, defining XOPEN_SOURCE or _XOPEN_SOURCE_EXTENDED selects 
ISO C APIs as well as the XPG4 extensions available in the header file. This mode of compilation makes XPG4 extensions 


visible. 
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Table 1-4 (Cont.) Feature Test Macros - Standards 


Other 
Standard Standards 
Macro Name Selected Implied Description 
__HIDE_FORBIDDEN_ When defined to the value 1, causes 
NAMES the C RTL headers that are named 


in the C standard to be configured 
such that they define only those 
identifiers that are specified as being 
defined by those headers under the 
version of the C standard in effect 
for the compilation, unless additional 
features are explicitly requested by 
other configuration macros (_XKOPEN_ 
SOURCE, for example). 


The C and C++ compilers will predefine 
this macro when certain language 
standard conformance features are 
selected, but the user can override 

any such predefinition by specifying 
/UNDEFINE=__HIDE_FORBIDDEN_ 
NAMES on the command line (or using 
#undef before including any headers). 
Conversely, the user can explicitly 
define the macro before including any 
headers, regardless of the language 
standard selected for the compiler. 


Features not defined by one of the previously named standards are considered 
HP C extensions and are selected by not defining any standards-related, feature- 
test macros. 


If you do not explicitly define feature test macros to control header file definitions, 
you implicitly include all defined symbols as well as HP C extensions. 


1.5.3 Interactions with the /STANDARD Qualifier 


The /STANDARD qualifier selects the dialect of the C language supported. 


With the exception of /STANDARD=ANSI89 and /STANDARD=ISOC94, the 
selection of C dialect and the selection of HP C RTL APIs to use are independent 
choices. All other values for /STANDARD cause the entire set of APIs to be 
available, including extensions. 


Specifying /STANDARD=ANSI89 restricts the default API set to the ANSI C 
set. In this case, to select a broader set of APIs, you must also specify the 
appropriate feature-test macro. To select the ANSI C dialect and all APIs, 
including extensions, undefine __ HIDE_FORBIDDEN_NAMES before including 
any header file. 


Compiling with /STANDARD=ISOC94 sets __STDC_VERSION__ to 199409. 
Conflicts that arise when compiling with both XPG4 and ISO C Amendment 1 
resolve in favor of ISO C Amendment 1. XPG4 extensions to ISO C Amendment 1 
are selected by defining _XOPEN_SOURCE. 
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The following examples help clarify these rules: 


1-22 Introduction 


The fdopen function is an ISO POSIX-1 extension to <stdio.h>. Therefore, 
<stdio.h> defines fdopen only if one or more of the following is true: 


-— The program including it is not compiled in strict ANSI C mode 
(/STANDARD=ANSI89). 


— _POSIX_C_SOURCE is defined as 1 or greater. 
— _XOPEN_SOURCE is defined. 
—- _XOPEN_SOURCE_EXTENDED is defined. 


The popen function is an ISO POSIX-2 extension to <stdio.h>. Therefore, 
<stdio.h> defines popen only if one or more of the following is true: 


— The program including it is not compiled in strict ANSI C mode 
(/STANDARD=ANSI89). 


— _POSIX_C_SOURCE is defined as 2 or greater. 
— _XOPEN_SOURCE is defined. 
—- _XOPEN_SOURCE_EXTENDED is defined. 


The getw function is an X/Open extension to <stdio.h>. Therefore, <stdio.h> 
defines getw only if one or more of the following is true: 


— The program is not compiled in strict ANSI C mode 
(/STANDARD=ANSI89). 


—- _XOPEN_ SOURCE is defined. 
— _XOPEN SOURCE_EXTENDED is defined. 


The X/Open Extended symbolic constants SC_PAGESIZE, SC_PAGE_SIZE, 
_SC_ATEXIT_ MAX, and _SC_IOV_MAX were added to <unistd.h> to 
support the sysconf function. However, these constants are not defined by 
_POSIX_C_SOURCE. 


The <unistd.h> header file defines these constants only if a program does not 
define _POSIX_C_SOURCE and does define XOPEN_SOURCE_EXTENDED. 


If _POSIX_C_SOURCE is defined, these constants are not visible in 
<unistd.h>. Note that _POSIX_C_SOURCE is defined only for programs 
compiled in strict ANSI C mode. 


The fgetname function is a HP C RTL extension to <stdio.h>. Therefore, 
<stdio.h> defines fgetname only if the program is not compiled in strict 
ANSI C mode (/STANDARD=ANSI89). 


The macro _PTHREAD_KEYS_MAX is defined by POSIX 1003.1c-1995. This 
macro is made visible in <limits.h> when compiling for this standard with _ 
POSIX_C_SOURCE == 199506 defined, or by default when compiling without 
any standards-defining, feature-test macros. 


The macro WCHAR_MAX defined in <wchar.h> is required by ISO C 
Amendment 1 but not by XPG4. Therefore: 


— Compiling for ISO C Amendment 1 makes this symbol visible, but 
compiling for XPG4 compliance does not. 


— Compiling for both ISO C Amendment 1 and XPG4 makes this symbol 
visible. 


Similarly, the functions wcsftime and wcstok in <wchar.h> are defined 
slightly differently by the ISO C Amendment 1 and XPG4: 


Compiling for ISO C Amendment 1 makes the ISO C Amendment 1 
prototypes visible. 


Compiling for XPG4 compliance makes the XPG4 prototypes visible. 


Compiling for both ISO C Amendment 1 and XPG4 selects the ISO C 
prototypes because conflicts resulting from this mode of compilation 
resolve in favor of ISO C. 


Compiling without any standard selecting feature test macros makes 
ISO C Amendment 1 features visible. 


In this example, compiling with no standard-selecting feature-test macros 
makes WCHAR_MAX and the ISO C Amendment 1 prototypes for wcesft ime 
and westok visible. 


e The wcswidth and wewidth functions are XPG4 extensions to ISO C 
Amendment 1. Their prototypes are in <wchar.h>. 


These symbols are visible if: 


Compiling for XPG4 compliance by defining XOPEN_SOURCE or _ 
XOPEN_SOURCE_EXTENDED. 


Compiling for DEC C Version 4.0 compatibility or on pre-OpenVMS 
Version 7.0 systems. 


Compiling with no standard-selecting feature-test macros. 


Compiling for both ISO C Amendment 1 and XPG4 compilance because 
these symbols are XPG4 extensions to ISO C Amendment 1. 


Compiling for strict ISO C Amendment 1 does not make them visible. 


1.5.4 Multiple-Version-Support Macro 


By default, the header files enable APIs in the HP C RTL provided by the version 
of the operating system on which the compilation occurs. This is accomplished by 
the predefined setting of the __VMS_VER macro, as described in the HP C User’s 
Guide for OpenVMS Systems. For example, compiling on OpenVMS Version 6.2 
causes only HP C RTL APIs from Version 6.2 and earlier to be made available. 


Another example of the use of the __ VMS_VER macro is support for the 64-bit 
versions of HP C RTL functions available with OpenVMS Alpha Version 7.0 
and higher. In all header files, functions that provide 64-bit support are 
conditionalized so that they are visible only if __VMS_VER indicates a version of 
OpenVMS that is greater than or equal to 7.0. 


To target an older version of the operating system, do the following: 


1. Define a logical DECC$SHR to point to the old version of DECC$SHR. The 
compiler uses a table from DECC$SHR to perform routine name prefixing. 


2. Define __VMS_VER appropriately, either with the /DEFINE qualifier or 
with a combination of the #undef and #define preprocessor directives. With 
/DEFINE, you may need to disable the warning regarding redefinition of a 
predefined macro. 
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Targeting a newer version of the operating system might not always be possible. 
For some versions, you can expect that the new DECC$SHR.EXE will require 
new features of the operating system that are not present. For such versions, the 
defining if the logical DECC$SHR in Step 1 would cause the compilation to fail. 


To override the value of __ VMS_VER, define __VMS_VER_OVERRIDE on the 
compiler command line. Defining __VMS_VER_OVERRIDE without a value sets 
__VMS_VER to the maximum value. 


1.5.5 Compatibility Modes 


1-24 


The following predefined macros are used to select header-file compatibility with 
previous versions of DEC C) or the OpenVMS operating system: 


e _DECC_V4_ SOURCE 
e _VMS_V6_SOURCE 
There are two types of incompatibilities that can be controlled in the header files: 


e To conform to standards, some changes are source-code incompatible but 
binary compatible. To select DEC C Version 4.0 source compatibility, use the 
_DECC_V4_SOURCE macro. 


e Other changes to conform to standards introduce a binary or run-time 
incompatibility. 
In general, programs that recompile get new behaviors. In these cases, use 
the VMS_V6_SOURCE feature test macro to retain previous behaviors. 


However, for the exit, kill, and wait functions, the OpenVMS Version 7.0 
changes to make these routines ISO POSIX-1 compliant were considered too 
incompatible to become the default. Therefore, in these cases the default 
behavior is the same as on pre-OpenVMS Version 7.0 systems. To access the 
versions of these routines that comply with ISO POSIX-1, use the _POSIX_ 
EXIT feature test macro. 


The following examples help clarify the use of these macros: 


e To conform to the ISO POSIX-1 standard, typedefs for the following have 
been added to <types.h>: 


dev_t off t 
gid t pid t 
ino t size t 
mode_t ssize t 
nlink t uid t 


Previous development environments using a version of DEC C earlier 

than Version 5.2 may have compensated for the lack of these typedefs in 
<types.h> by adding them to another module. If this is the case on your 
system, then compiling with the <types.h> provided with DEC C Version 5.2 
might cause compilation errors. 

To maintain your current environment and include the DEC C Version 

5.2 <types.h>, compile with _DECC_V4_SOURCE defined. This will omit 
incompatible references from the DEC C Version 5.2 headers. In <types.h>, 
for example, the previously listed typedefs will not be visible. 


e As of OpenVMS Version 7.0, the HP C RTL getuid and geteuid functions are 
defined to return an OpenVMS UIC (user identification code) that contains 
both the group and member portions of the UIC. In previous versions of the 
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DEC C RTL, these functions returned only the member number from the UIC 
code. 


Note that the prototypes for getuid and geteuid in <unistd.h> (as 
required by the ISO POSIX-1 standard) and in <unixlib.h> (for HP C 

RTL compatibility) have not changed. By default, newly compiled programs 
that call getuid and geteuid get the new definitions. That is, these functions 
will return an OpenVMS UIC. 


To let programs retain the pre-OpenVMS Version 7.0 behavior of getuid and 
geteuid, compile with the VMS_V6_SOURCE feature-test macro defined. 


As of OpenVMS Version 7.0, the HP C RTL exit function is defined with ISO 
POSIX-1 semantics. As a result, the input status argument to exit takes 

a number between 0 and 255. (Prior to this, exit could take an OpenVMS 
condition code in its status parameter.) 


By default, the behavior for exit on OpenVMS systems is the same as 
before: exit accepts an OpenVMS condition code. To enable the ISO POSIX-1 
compatible exit function, compile with the _POSIX_EXIT feature-test macro 
defined. 


1.5.6 Curses and Socket Compatibility Macros 


The following feature-test macros are used to control the Curses and Socket 
subsets of the HP C RTL library: 


_BSD44_CURSES 

This macro selects the Curses package from the 4.4BSD Berkeley Software 
Distribution. 

_VMS_CURSES 

This macro selects a Curses package based on the VAX C compiler. This is 
the default Curses package. 

_SOCKADDR_LEN 


This macro is used to select 4.4BSD-compatible and XPG4 V2-compatible 
socket interfaces. These interfaces require support in your underlying TCP/IP 
software. Contact your TCP/IP vendor to inquire if the version of TCP/IP 
software you run supports 4.4BSD sockets. 


Strict XPG4 V2 compliance requires the 4.4BSD-compatible socket interface. 
Therefore, if XOPEN_SOURCE_EXTENDED is defined on OpenVMS Version 7.0 
or higher, SOCKADDR_LEN is defined to be 1. 


The following examples help clarify the use of these macros: 


Symbolic constants like AE, AL, AS, AM, BC, which represent pointers 
to termcap fields used by the BSD Curses package, are only visible in 
<curses.h> if _BSD44_CURSES is defined. 


The <socket .h> header file defines a 4.4BSD sockaddr structure only if _ 
SOCKADDR_LEN or _XOPEN_SOURCE_EXTENDED is defined. Otherwise, 
<socket .h> defines a pre-4.4BSD sockaddr structure. If SOCKADDR_LEN 
is defined and XOPEN_SOURCE_EXTENDED is not defined, 


The <socket.h> header file also defines an osockaddr structure, which is a 
4.3BSD sockaddr structure to be used for compatibility purposes. Since XPG4 
V2 does not define an osockaddr structure, it is not visible in XOPEN_ 
SOURCE_EXTENDED mode. 
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1.5.7 2-Gigabyte File Size Macro 


The C RTL provides support for compiling applications to use file sizes and offsets 
that are two gigabytes (GB) and larger. This is accomplished by allowing file 
offsets of 64-bit integers. 


The fseeko and ftello functions, which have the same behavior as fseek and 
ftell, accept or return values of type off_t, which allows for a 64-bit variant of 
off t to be used. 


C RTL functions lseek, mmap, ftuncate, truncate, stat, fstat, and ftw can also 
accommodate a 64-bit file offset. 


The new 64-bit interfaces can be selected at compile time by defining the _ 
LARGEFILE feature macro. 


1.5.8 32-Bit UID and GID Macro aia, 164) 


The C RTL supports 32-bit User Identification (UID) and Group Identification 
(GID). When an application is compiled to use 32-bit UID/GID, the UID and GID 
are derived from the UIC as in previous versions of the operating system. 


To compile an application for 16-bit UID/GID support on systems that by default 
use 32-bit UIDs/GIDs, define the _DECC_SHORT_GID_T macro to 1. 


Not specifying _DECC_SHORT_GID_T provides long (32-bit) UID/GID. 


Compiling on older OpenVMS systems where long UID/GID is not supported, 
or compiling for legacy compatibility (_.DECC_V4_SOURCE for HP C Version 
4 or _VMS_V6_SOURCE for OpenVMS Version 6), forces use of short (16-bit) 
UID/GID. 


1.5.9 Standard-Compliant stat Structure dipic, 16 


The C RTL supports an X/Open standard-compliant definition of the stat 
structure and associated definitions. To use these new definitions, applications 
must compile with the USE_STD_STAT feature-test macro defined. Use of 
_USE_STD_STAT specifies long (32-bit) GIDs. 


When compiled with USE_STD_STAT, the stat structure includes these changes: 


e Type ino t is defined as an unsigned quadword int. Without USE_STD_ 
STAT, it is an unsigned short. 


e Type dev _t is defined as a 64-bit integer. Without _USE_STD_STAT, it is a 
32-bit character pointer. 


e Type off _t is defined as a 64-bit integer, as if the LARGEFILE macro has 
been defined. Without USE_STD_STAT, of f_t is a 32-bit integer. 


e Fields st_dev and st_rdev will have unique values per device. Without 
_USE_STD_STAT, uniqueness is not assured. 


e Fields st_blksize and st_blocks are added. Without _USE_STD_STAT, 
these fields do not exist. 
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1.5.10 Using Legacy _toupper and _tolower Behavior (pia, 164) 


As of OpenVMS Version 8.3, to comply with the C99 ANSI standard and X/Open 
Specification, the tolower and toupper macros by default do not evaluate their 
parameter more than once. They simply call their respective tolower or toupper 
function. This avoids side effects (such as i++ or function calls) where the user 
can tell how many times an expression is evaluated. 


To retain the older, optimized behavior of the tolower and toupper macros, 
compile with /DEFINE=_FAST_TOUPPER. Then, as in previous releases, these 
macros optimize the call to avoid the overhead of a runtime call. However, the 
macro’s parameter is evaluated more than once to determine how to calculate the 
result, possibly creating unwanted side effects. 


1.5.11 Using Faster, Inlined Put and Get Functions dipia, 164 
Compiling with the __ UNIX_PUTC macro defined enables an optimization that 
sets the following I/O functions to use faster, inlined functions: 


fgetc 

fputc 

putc 

putchar 
fgetc_unlocked 
fputc_unlocked 
putc_unlocked 
putchar_ unlocked 


1.5.12 POSIX Style exit (pre, 164) 


The HP C and C++ Version 7.1 and higher compilers have a /MAIN=POSIX_EXIT 
qualifier that defines the _POSIX_EXIT macro and causes the main program to 
call __ posix exit instead of exit when returning from the main program. 


This qualifier should be used with programs ported from UNIX that do not 
explicitly call exit and do not use OpenVMS specific exit codes. 


For older compilers, the following sample code can be used to force the existing 
main module to have a different name so that a simple main program will call it 
but force the exit status to be through the _ posix _exit call. 


The replacement main function can be in a different module, so that 
/DEFINE="main=real_main" is all that is needed for modifying the build of 
the existing main function. 


#define POSIX EXIT 1 
#include <stdlib.h> 
int real_main(int argc, char **argv) ; 


/* Make sure POSIXized exit is used */ 
int main(int argc, char **argv) 


int ret_status; 
ret_status = real _ main(argc, argv); 


exit (ret_status) ; 


#define main real main 
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Unless your C program is intentionally using OpenVMS status codes for exit 
values, it is strongly recommended that both the _POSIX_EXIT macro be defined 
and, if needed, the /MAIN=POSIX_EXIT or the alternative main replacement be 
used so that DCL, BASH, and the accounting file get usuable exit values. 


1.6 Enabling C RTL Features Using Feature Logical Names 


The C RTL provides an extensive list of feature switches that can be set using 
DECC$ logical names. These switches affect the behavior of a C application at 
run time. 


The feature switches introduce new behaviors and also preserve old behaviors 
that have been deprecated. 


You enable most features by setting a logical name to ENABLE and disable a 
feature by setting the logical name to DISABLE: 


$ DEFINE DECCS$feature ENABLE 
$ DEFINE DECC$feature DISABLE 


Some feature logical names can be set to a numeric value. For example: 


$ DEFINE DECCSPIPE BUFFER SIZE 32768 


Notes 


e Do not set C RTL feature logical names for the system. Set them 
only for the applications that need them, because other applications 
including OpenVMS components depend on the default behavior of 
these logical names. 


e Older feature logicals from earlier releases of the C Run-Time Library 
were documented as supplying "any equivalence string" to enable a 
feature. While this was true at one time, we now strongly recommend 
that you use ENABLE for setting these feature logicals and DISABLE 
for disabling them. Failure to do so may produce unexpected results. 


The reason for this is twofold: 


— In previous versions of the C RTL, any equivalence string, even 
DISABLE, may have enabled a feature logical. 


— In subsequent and current versions of the C RTL, the following 
equivalence strings will disable a feature logical. Do not use them 
to enable a feature logical. 


DISABLE 
0 (zero) 

F 

FALSE 

N 

NO 


Any other string not on this list will enable a feature logical. The 
unintentionally misspelled string "DSABLE", for example, will 
enable a feature logical. 
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The C RTL also provides several functions to manage feature logicals within your 
applications: 


deccSfea 
deccSfea 
deccSfea 
deccSfea 
deccSfea 
deccSfea 
deccSfea 
deccSfea 


ure get 
ure_get_value 
ure_get_index 
ure_get_name 
ure_set 
ure_set_value 
ure_show 

ure show all 


See the reference section for more information on these functions. 


Table 1-5 lists the C RTL feature logical names, grouped by the type of features 
they control. 


Table 1-5 C RTL Feature Logical Names 
Feature Logical Name Default 


Performance Optimizations 


DECC$ENABLE_GETENV_CACHE DISABLE 
DECC$LOCALE_CACHE_SIZE 0 
DECC$TZ_CACHE_SIZE 2 


Legacy Behaviors 


DECC$ALLOW_UNPRIVILEGED_NICE DISABLE 
DECC$NO_ROOTED_SEARCH_LISTS DISABLE 
DECC$THREAD_DATA AST SAFE DISABLE 
DECC$V62_RECORD_GENERATION DISABLE 
DECC$WRITE_SHORT_RECORDS DISABLE 
DECC$XPG4_STRPTIME DISABLE 


File Attributes 


DECC$DEFAULT_LRL 32767 
DECC$DEFAULT_UDF_RECORD DISABLE 
DECC$FIXED_LENGTH_SEEK_TO_EOF DISABLE 
DECC$ACL_ACCESS_CHECK DISABLE 
Mailboxes 

DECC$MAILBOX_CTX_STM DISABLE 


Changes for UNIX Conformance 


DECC$SELECT_IGNORES_INVALID_FD DISABLE 
DECC$STRTOL_ERANGE DISABLE 
DECC$VALIDATE_SIGNAL_IN_KILL DISABLE 


(continued on next page) 
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Table 1-5 (Cont.) C RTL Feature Logical Names 


Feature Logical Name Default 
General UNIX Enhancements 

DECC$UNIX_LEVEL DISABLE 
DECC$ARGV_PARSE_STYLE DISABLE 
DECC$PIPE_BUFFER_SIZE 512 
DECC$PIPE_BUFFER_QUOTA 512 
DECC$STREAM_PIPE DISABLE 
DECC$POPEN_NO_CRLF_REC_ATTR DISABLE 
DECC$STDIO_CTX_EOL DISABLE 
DECC$USE_RAB64 DISABLE 
DECC$GLOB_UNIX_STYLE DISABLE 
Enhancements for UNIX Style File Names 
DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION DISABLE 
DECC$EFS_CHARSET DISABLE 
DECC$ENABLE_TO_VMS_LOGNAME_CACHE ENABLE 
DECC$FILENAME_UNIX_NO_VERSION DISABLE 
DECC$FILENAME_UNIX_REPORT DISABLE 
DECC$READDIR_DROPDOTNOTYPE DISABLE 
DECC$RENAME_NO_INHERIT DISABLE 
DECC$RENAME_ALLOW_DIR DISABLE 
Enhancements for UNIX Style File Attributes 
DECC$EFS_FILE_TIMESTAMPS DISABLE 
DECC$EXEC_FILEATTR_INHERITANCE DISABLE 
DECC$FILE_OWNER_UNIX DISABLE 
DECC$FILE_PERMISSION_UNIX DISABLE 
DECC$FILE_SHARING DISABLE 
UNIX Compliance Mode 

DECC$DETACHED_CHILD_PROCESS DISABLE 
DECC$FILENAME_UNIX_ONLY DISABLE 
DECC$POSIX_STYLE_UID DISABLE 
DECC$USE_JPI$_CREATOR DISABLE 
New Behaviors for POSIX Conformance 
DECC$ALLOW_REMOVE_OPEN_FILES DISABLE 
DECC$POSIX_SEEK_STREAM_FILE DISABLE 


DECC$UMASK 
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RMS default 
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Table 1-5 (Cont.) C RTL Feature Logical Names 


Feature Logical Name Default 


File-Name Handling 


DECC$POSIX_COMPLIANT_PATHNAMES DISABLE 
DECC$DISABLE_POSIX_ROOT ENABLE 
DECC$EFS_CASE_PRESERVE DISABLE 
DECC$EFS_CASE_SPECIAL DISABLE 
DECC$EFS_NO_DOTS_IN_DIRNAME DISABLE 
DECC$READDIR_KEEPDOTDIR DISABLE 
DECC$UNIX_PATH_ BEFORE_LOGNAME DISABLE 


An alphabetic listing and description of the C RTL feature logical names follows. 
Unless otherwise stated, the feature logicals are enabled with ENABLE and 
disabled with DISABLE. 


DECC$ACL_ACCESS_CHECK 
The DECC$ACL_ACCESS_CHECK feature logical controls the behavior of the 
access function. 


With DECC$ACL_ACCESS_CHECK enabled, the access function checks both 
UIC protection and OpenVMS Access Control Lists (ACLs). 


With DECC$ACL_ACCESS_CHECK disabled, the access function checks only 
UIC protection. 


DECCS$ALLOW_REMOVE_OPEN_FILES 

The DECC$ALLOW_REMOVE_OPEN_FILES feature logical controls the 
behavior of the remove function on open files. Ordinarily, the operation fails. 
However, POSIX conformance dictates that the operation succeed. 


With DECC$ALLOW_REMOVE_OPEN_FILES enabled, this POSIX conformant 
behavior is achieved. 


DECCS$ALLOW_UNPRIVILEGED_NICE 

With DECC$ALLOW_UNPRIVILEGED_NICE enabled, the nice function exhibits 
its legacy behavior of not checking the privilege of the calling process (that is, 
any user may lower the nice value to increase process priorities). Also, when 
the caller sets a priority above MAX_PRIORITY, the nice value is set to the base 
priority. 


With DECC$ALLOW_UNPRIVILEGED_NICE disabled, the nice function 
conforms to the X/Open standard of checking the privilege of the calling process 
(only users with ALTPRI privilege can lower the nice value to increase process 
priorities), and when the caller sets a priority above MAX_PRIORITY, the nice 
value is set to MAX_PRIORITY. 


DECCSARGV_PARSE_STYLE 

With DECC$ARGV_PARSE_STYLE enabled, case is preserved in command-line 
arguments when the process has been set up for extended DCL parsing using 
SET PROCESS/PARSE_STYLE=EXTENDED. 


DECC$ARGV_PARSE_STYLE must be defined externally as a logical name or 
set in a function called using the LIB$INITIALIZE mechanism because it is 
evaluated before function main is called. 
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DECC$DEFAULT_LRL 

DECC$DEFAULT_LRL specifies the default value for the RMS attribute for 
the longest record length. The default value 32767 is the largest record size 
supported by RMS. 


Default: 32767 
Maximum: 32767 


DECC$DEFAULT_UDF_RECORD 
With DECC$DEFAULT_UDF_RECORD enabled, file access mode defaults to 
RECORD instead of STREAM mode for all files except STREAMLF. 


DECC$DETACHED_CHILD_PROCESS 
With DECC$DETACHED_CHILD_PROCESS enabled, child processes created 
using vfork and exec are created as detached processes instead of subprocesses. 


This feature has only limited support. In some cases the console cannot be shared 
between the parent process and the detached process, which can cause exec to 
fail. 


DECCS$DISABLE_POSIX_ROOT 
With DECC$DISABLE_POSIX_ROOT enabled, support for the POSIX root 
directory defined by SYS$POSIX_ROOT is disabled. 


With DECC$DISABLE_POSIX_ROOT disabled, the SYS$POSIX_ROOT logical 
name is interpreted as the equivalent of the file path "/". If a UNIX path 
starting with a slash (/) is given and the value after the leading slash cannot be 
translated as a logical name, SYS$POSIX_ROOT is used as the parent directory 
for the specified UNIX file path. 


The C RTL supports a UNIX style root that behaves like a real directory. This 
allows such actions as: 


cd / 

mkdir /dirname 

tar -xvf tarfile.tar /dirname 
ls / 


AP ol ol? 


oe 


Previously, the C RTL did not recognize "/" as a directory name. The normal 
processing for a file path starting with '/" was to interpret the first element as a 
logical name or device name. If this failed, there was special processing for the 
name /dev/null and names starting with /bin and /tmp: 


/dev/null NLAO: 
/bin SYSSSYSTEM: 
/tmp SYSS$SCRATCH: 


These behaviors are retained for compatibility purposes. In addition, support 
has been added to the C RTL for the logical name SYS$POSIX_ROOT as an 
equivalent to '/". 


To enable this feature for use by the C RTL, define SYS$POSIX_ROOT as a 
concealed logical name. For example: 


$ DEFINE/TRANSLATION= (CONCEALED , TERMINAL) SYSSPOSIX_ ROOT "S1SDKAO: [SYSO.abc.]" 
To disable this feature: 
S$ DEFINE DECCSDISABLE POSIX ROOT DISABLE 
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Enabling SYS$POSIX_ROOT results in the following behavior: 


e If the existing translation of a UNIX path starting with "/" fails and 
SYS$POSIX_ROOT is defined, the name is interpreted as if it starts with 
/sys$posix root. 


e When converting from an OpenVMS to a UNIX style file name, and the 
OpenVMS name starts with "SYS$POSIX_ROOT:", then the "SYS$POSIX_ 
ROOT:" is removed. For example, SYS$POSIX_ROOT: [dirname] becomes 
/dirname. If the resulting name could be interpreted as a logical name or 
one of the special cases previously listed, the result is /./dirname instead of 
/dirname. 


DECCS$DISABLE_TO_VMS_LOGNAME_TRANSLATION 

With DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION enabled, the 
conversion routine decc$to_vms will only treat the first element of a UNIX style 
name as a logical name if there is a leading slash (/). 


DECCSEFS_CASE_PRESERVE 
With DECC$EFS_CASE_PRESERVE enabled, case is preserved for file names on 
ODS-5 disks. 


With DECC$EFS_CASE_PRESERVE disabled, UNIX style file names are always 
reported in lowercase. 


However, note that enabling DECC$EFS_CASE_SPECIAL overrides the setting 
for DECC$EFS_CASE_PRESERVE. 


DECC$EFS_CASE_SPECIAL 

With DECC$EFS_CASE_SPECIAL enabled, case is preserved only for file names 
containing lowercase. If an element of a file name contains all uppercase letters, 
it is reported in all lowercase in UNIX style. 


When enabled, DECC$EFS_CASE_SPECIAL overrides the value of DECC$EFS_ 
CASE_PRESERVE. 


DECCS$EFS_CHARSET 

With DECC$EFS_CHARSET enabled, UNIX names can contain ODS-5 extended 
characters. Support includes multiple dots and all ASCII characters in the range 
0 to 255, except the following: 

<NUL> 


* 
" bo) 


Unless DECC$FILENAME_UNIX_ONLY is enabled, some characters can be 
interpreted as OpenVMS characters depending on context. They are: 


< 


DECC$EFS_CHARSET might be necessary for existing applications that make 
assumptions about file names based on the presence of certain characters, 
because the following nonstandard and undocumented C RTL extensions do not 
work when EFS extended character-set support is enabled: 


e $HOME is interpreted as the user’s login directory 


With DECC$EFS_CHARSET enabled, $HOME is treated literally and may be 
in an OpenVMS or UNIX style file name. 
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e ~name is interpreted as the login directory for user name 


With DECC$EFS_CHARSET enabled, ~name is treated literally and can be in 
an OpenVMS or UNIX style file name. 


e Wild card regular expressions in the form [a-z] 
With DECC$EFS_CHARSET enabled, square brackets are acceptable in 
OpenVMS and UNIX style file names. For instance, in a function such as 
open, abc [a-z]lef.txt is interpreted as a UNIX style name equivalent to the 
OpenVMS style name abc’ [a-z*Jef.txt, and [a-z]bc is interpreted as an 
OpenVMS style name equivalent to the UNIX style name /sys$disk/a-z/bc. 


With DECC$EFS_CHARSET enabled, the following encoding for EFS extended 
characters is supported when converting from an OpenVMS style file name to a 
UNIX style file name: 


e All ODS-2 compatible names 


e All encoding for 8-bit characters, either as single byte or using two-digit 
hexadecimal form “ab. In a UNIX path these are always represented as a 
single byte. 


e Encoding for DEL (47F) 

e The following characters when preceded by a caret: 
space! , &'’ ()+@{};#[]%*=+$-~%. 

e The following characters when not preceded by a caret: 
es 


e The implementation supports the conversion from OpenVMS to UNIX needed 
for functions readdir, ftw, getname, fgetname, getcwd, and others. 


DECCS$EFS_FILE_TIMESTAMPS 

With DECC$EFS_FILE_TIMESTAMPS enabled, stat and fstat report new 
ODS-5 access time (st_atime), attribute revision time (st_ctime) and modification 
time (st_mtime) for files on ODS-5 volumes that have the extended file times 
enabled using SET VOLUME/VOLUME=ACCESS_DATES. 


If DECC$EFS_FILE_TIMESTAMPS is disabled, or the volume is not ODS-5, or 
the volume does not have support for these additional times enabled, st_ctime 
continues to be the file creation time and st_atime the same as the st_mtime. 


The utime and utimes functions support these ODS-5 times in the same way as 
stat. 


DECC$EFS_NO_DOTS_IN_DIRNAME 

With support for extended characters in file names for ODS-5, a name such as 
NAME.EXT can be interpreted as NAME.EXT.DIR. Determining if directory 
[.name”.ext] exists adds overhead to UNIX name translation when support for 
extended character support in UNIX file names is enabled. 


Enabling the DECC$EFS_NO_DOTS_IN_DIRNAME feature logical suppresses 
the interpretation of a file name containing dots as a directory name. With this 
logical enabled, NAME.EXT is assumed to be a file name; no check is made for 
directory [.name”’.ext]. 


DECCS$ENABLE_GETENV_CACHE 
The C RTL supplements the list of environment variables in the environ table 
with all logical names and DCL symbols available to the process. 
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By default, whenever getenv is called for a name not in the environ table, an 
attempt is made to resolve this as a logical name and, if this fails, as a DCL 
symbol. 


With DECC$ENABLE_GETENV_CACHE enabled, once a logical name or DCL 
name has been successfully translated, its value is stored in a cache. When the 
same name is requested in a future call to getenv, the value is returned from the 
cache instead of reevaluating the logical name or DCL symbol. 


DECCS$ENABLE_TO_VMS_LOGNAME_CACHE 

Use the DECC$ENABLE_TO_VMS_LOGNAME_ CACHE to improve the 
performance of UNIX name translation. The value is the life of each cache 
entry in seconds. The equivalence string ENABLE is evaluated as 1 second. 


Define DECC$ENABLE_TO_VMS_LOGNAME_CACHE to 1 to enable the cache 
with a 1-second life for each entry. 


Define DECC$ENABLE_TO_VMS_LOGNAME_CACHE to 2 to enable the cache 
with a 2-second life for each entry. 


Define DECC$ENABLE_TO_VMS_LOGNAME_CACHE to —1 to enable the cache 
without a cache entry expiration. 


DECC$EXEC_FILEATTR_INHERITANCE 
The DECC$EXEC_FILEATTR_INHERITANCE feature logical affects child 
processes that are C programs. 


For versions of OpenVMS before Version 7.3-2, DECC$EXEC_FILEATTR_ 
INHERITANCE is either enabled or disabled: 


e With DECC$EXEC_FILEATTR_INHERITANCE enabled, the current file 
pointer and the file open mode is passed to the child process in exec calls. 


e With this logical name disabled, the child process does not inherit append 
mode or the file position. 


For OpenVMS Version 7.3-2 and higher, DECC$EXEC_FILEATTR_ 
INHERITANCE can be defined to 1 or 2, or be disabled: 


e With DECC$EXEC_FILEATTR_INHERITANCE defined to 1, a child process 
inherits file positioning for all file access modes except append. 


e With DECC$EXEC_FILEATTR_INHERITANCE defined to 2, a child process 
inherits file positioning for all file access modes including append. 


e With DECC$EXEC_FILEATTR_INHERITANCE disabled, a child process does 
not inherit the file position for any access modes. 


DECCS$FILENAME_UNIX_ONLY 
With DECC$FILENAME_UNIX_ONLY enabled, file names are never interpreted 
as OpenVMS style names. This prevents any interpretation of the following as 
OpenVMS special characters: 

ro 


DECCS$FILENAME_UNIX_NO_VERSION 
With DECC$FILENAME_UNIX_NO_VERSION enabled, OpenVMS version 
numbers are not supported in UNIX style file names. 


With DECC$FILENAME_UNIX_NO_VERSION disabled, in UNIX style names, 
version numbers are reported preceded by a period (. ). 
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DECCS$FILENAME_UNIX_REPORT 

With DECC$FILENAME_UNIX_REPORT enabled, all file names are reported in 
UNIX style unless the caller specifically selects OpenVMS style. This applies to 
getpwnam, getpwuid, argv[0], getname, fgetname, and tempnam. 


With DECC$FILENAME_UNIX_REPORT disabled, unless specified in the 
function call, file names are reported in OpenVMS style. 


DECC$FILE_PERMISSION_UNIX 

With DECC$FILE_PERMISSION_UNIX enabled, the file permissions for new 
files and directories are set according to the file creation mode and umask. 

This includes mode 0777. When an earlier version of the file exists, the file 
permissions for the new file are inherited from the earlier version. This mode 
sets DELETE permission for a new directory when WRITE permission is enabled. 


With DECC$FILE_PERMISSION_UNIX disabled, modes 0 and 0777 indicate 
using RMS default protection or protection from the previous version of the file. 
Permissions for new directories also follow OpenVMS rules, including disabling 
DELETE permissions. 


DECC$FILE_SHARING 

With DECC$FILE_SHARING enabled, all files are opened with full sharing 
enabled (FAB$M_DEL | FAB$M_GET | FAB$M_PUT | FAB$M_UPD). This is 
set as a logical OR with any sharing mode specified by the caller. 


DECCS$FIXED_LENGTH_SEEK_TO_EOF 

With DECC$FIXED_ LENGTH SEEK TO _EOF enabled, lseek, fseeko, and 
fseek with the direction paremeter set to SEEK_END will position relative to the 
last byte in the file for files with fixed-length records. 


With DECC$FIXED_LENGTH_SEEK_TO_EOF disabled, lseek, fseek, and 
fseeko when called with SEEK_EOF on files with fixed-length records, will 
position relative to the end of the last record in the file. 


DECC$GLOB_UNIX_STYLE 

Enabling DECC$GLOB_UNIX_STYLE selects the UNIX mode of the glob 
function, which uses UNIX style filenames and wildcards instead of OpenVMS 
style filenames and wildcards. 


DECC$LOCALE_CACHE_SIZE 
DECC$LOCALE_CACHE_SIZE defines how much memory, in bytes, to allocate 
for caching locale data. The default value is 0, which disables the locale cache. 


Default: 0 
Maximum: 2147483647 


DECCS$MAILBOX_CTX_STM 
By default, an open on a local mailbox that is not a pipe treats mailbox records as 
having a record attribute of FAB$M_CR. 


With DECC$MAILBOX_CTX_STM enabled, the record attribute FAB$M_CR is 
not set. 


DECC$NO_ROOTED_SEARCH_LISTS 
When the decc$to_vms function evaluates a UNIX style path string, if it 
determines the first element to be a logical name, then: 


e For rooted logicals or devices, it appends ":[000000]" to the logical name. 
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For example, if log1 is a rooted logical (S(DEFINE LOG1 [DIR_NAME.]) then 
/log1/filename.ext translates to LOG1:[000000] FILENAME.EXT. 


e For nonrooted logicals, it appends just a colon (:) to the logical name. 


For example, if log2 is a nonrooted logical ($ DEFINE LOG2 [DIR_NAME)), 
then /log2/filename.ext translates to LOG2:FILENAME.EXT. 


e If the first element is a search-list logical, the translation proceeds by 
evaluating the first element in the search list, and translating the path as 
previously described. 


The preceding three cases lead to predictable, expected results. 


In the case where the first element is a search list that consists of a mixture of 
rooted and nonrooted logicals, translating paths as described previously can lead 
to different behavior from that of older versions of OpenVMS (before OpenVMS 
Version 7.3-1): 


e Before OpenVMS Version 7.3-1, regardless of the contents of the logical, 
the decc$to_vms function appended only a colon (:). For search lists that 
consisted of a mixture of rooted and nonrooted logicals, this resulted in 
certain expected behaviors. 


e For OpenVMS Version 7.3-1 and later, if the first element of the mixed search 
list is a rooted logical, then decc$to_vms appends ":[000000]" to the logical 
name, resulting in different behavior from that of OpenVMS releases prior to 
Version 7.3-1. 


DECC$NO_ROOTED_SEARCH_LISTS controls how the decc$to_vms function 
resolves search-list logicals and provides a means to restore the OpenVMS 
behavior prior to Version 7.3-1. 


With DECC$NO_ROOTED_SEARCH_LISTS enabled: 


e Ifa logical is detected in a file specification, and it is a search list, then a 
colon (:) is appended when forming the OpenVMS file specification. 


e If it is not a search list, the behavior is the same as with DECC$NO_ 
ROOTED_SEARCH_LISTS disabled. 


Enabling this feature logical provides the pre-Version 7.3-1 behavior for search 
list logicals. 


With DECC$NO_ROOTED_SEARCH_LISTS disabled: 


e Ifa logical is detected in a file specification, and it is a rooted logical (or 
a search list whose first element is a rooted logical), then ":[000000]" is 
appended when forming the OpenVMS file specification. 


e Ifit is a nonrooted logical (or a search list whose first element is a nonrooted 
logical), then just a colon (:) is appended. 


Disabling this feature logical provides the behavior for OpenVMS Version 7.3-1 
and later. 


DECC$PIPE_BUFFER_QUOTA 

OpenVMS Version 7.3-2 adds an optional fourth argument of type int to the pipe 
function to specify the buffer quota of the pipe’s mailbox. In previous OpenVMS 
versions, the buffer quota was equal to the buffer size. 


DECC$PIPE_BUFFER_QUOTA lets you specify a buffer quota to use for the pipe 
function if the optional fourth argument of that function is omitted. 
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If the optional pipe fourth argument is omitted and DECC$PIPE_BUFFER_ 
QUOTA is not defined, then the buffer quota defaults to the buffer size, as before. 


Default: 512 
Minimum: 512 


Maximum: 2147483647 


DECC$PIPE_BUFFER_SIZE 

The system default buffer size of 512 bytes for pipe write operations can limit 
performance and generate extra line feeds when handling messages longer than 
512 bytes. 


DECC$PIPE_BUFFER_SIZE allows a larger buffer size to be used for pipe 
functions such as pipe and popen. A value of 512 to 65535 bytes can be specified. 


If DECC$PIPE_BUFFER_SIZE is not specified, the default buffer size 512 is 
used. 


Default: 512 
Minimum: 512 


Maximum: 65535 


DECCS$POPEN_NO_CRLF_REC_ATTR 

With DECC$POPEN_NO_CRLF_REC_ATTR disabled, a pipe opened with the 
popen function has its record attributes set to CR/LF carriage control (fab$b_rat 
| = FAB$M_CR). This is the default behavior. 


With DECC$POPEN_NO_CRLF_REC_ATTR enabled, CR/LF carriage control is 
prevented from being added to the pipe records. This is compatible with UNIX 
behavior, but be aware that enabling this feature might result in undesired 
behavior from other functions, such as gets, that rely on the carriage-return 
character. 


DECC$POSIX_COMPLIANT_PATHNAMES 

With DECC$POSIX_COMPLIANT_PATHNAMES enabled, an application is 
allowed to present POSIX-compliant pathnames to any C RTL function that 
accepts a pathname. 


By default DECC$POSIX_COMPLIANT_PATHNAMES is disabled, and the 
usual C RTL behavior prevails. This disabled mode includes interpretation of 
pathnames as UNIX style specifications and uses rules that are different and 
unrelated to POSIX-compliant pathname processing. 


To enable DECC$POSIX_COMPLIANT_PATHNAMES, set it to one of the 
following values: 
1 All pathnames are designated as POSIX style. 


2 Pathnames that end in ":" or contain any of the bracket characters "[] <>", and 
that can be successfully parsed by the SYS$FILESCAN service, are designated as 
OpenVMS style. Otherwise, they are designated as POSIX style. 


moo 


3 The pathnames "." and "..", or pathnames that contain "/" are designated as 
POSIX style. Otherwise, they are designated as OpenVMS style. 


4 All pathnames are designated as OpenVMS style. 


See Section 12.3.1 for more information. 
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DECC$POSIX_SEEK_STREAM_FILE 

With DECC$POSIX_SEEK_STREAM_FILE enabled, positioning beyond end-of- 
file on STREAM files does not write to the file until the next write. If the write 
is beyond the current end-of-file, this positions beyond the old end-of-file, and the 
start position for the write is filled with zeros. 


With DECC$POSIX_SEEK_STREAM_FILE disabled, positioning beyond end-of- 
file will immediately write zeros to the file from the current end-of-file to the new 
position. 


DECCS$POSIX_STYLE_UID 
With DECC$POSIX_STYLE_UID enabled, 32-bit UIDs and GIDs are interpreted 
as POSIX style identifiers. 


With this logical name disabled, UIDs and GIDs are derived from the process 
UIC. 


This feature is only available on OpenVMS systems providing POSIX style UID 
and GID support. 


DECC$READDIR_DROPDOTNOTYPE 
With DECC$READDIR_DROPDOTNOTYPE enabled, readdir when reporting 
files in UNIX style only reports the trailing period (.) for files with no file type 
when the file name contains a period. 


With this logical name disabled, all files without a file type are reported with a 
trailing period. 


DECC$READDIR_KEEPDOTDIR 
The default behavior when reporting files in UNIX style from readdir is to report 
directories without a file type. 


With DECC$READDIR_KEEPDOTDIR enabled, directories are reported in UNIX 
style with a file type of ".DIR". 


DECCSRENAME_NO_INHERIT 

DECC$RENAME_NO_INHERIT provides more UNIX compliant behavior in the 
rename function. With DECC$RENAME_NO_INHERIT enabled, the following 
behaviors are enforced: 


e Ifthe old argument points to the pathname of a file that is not a directory, 
the new argument will not point to the pathname of a directory. 


e The new argument cannot point to a directory that exists. 


e Ifthe old argument points to the pathname of a directory, the new argument 
will not point to the pathname of a file that is not a directory. 


e The new name for the file does not inherit anything from the old name. The 
new name must be specified completely. For example: 


Renaming "A.A" to "B" yields "B" 


With this logical name disabled, you get the expected OpenVMS behavior. For 
example: 


Renaming "A.A" to "B" yields "B.A" 
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DECC$RENAME_ALLOW_DIR 

Enabling DECC$RENAME_ALLOW_DIR restores the prior OpenVMS behavior of 
the rename function by allowing conversion to a directory specification when the 
second argument is an ambiguous file specification passed as a logical name. The 
ambiguity is whether the logical name is a UNIX or OpenVMS file specification. 
Consider the following example with DECC$RENAME_ALLOW_DIR enabled: 


rename ("file.ext", "logical name") /* where logical name = dev: [dir.subdir] */ 
/* and :[dir.subdir] exists. */ 


This results in: 
dev: [dir. subdir] file.ext 
This example renames a file from one directory into another directory, which is 


the same behavior as in legacy versions of OpenVMS (versions before 7.3-1). Also 
in this example, if dev: [dir.subdir] does not exist, rename returns an error. 


Disabling DECC$RENAME_ALLOW_DIR provides a more UNIX compliant 
conversion of the "logical name" argument of rename. Consider the following 
example with DECC$RENAME_ALLOW_DIR disabled: 


rename ("file.ext", "logical name") /* where logical_name = dev: [dir.subdir] */ 
This results in: 
dev: [dir] subdir.ext 


This example renames the file using the subdir part of the "logical name" 
argument as the new file name because on UNIX systems, renaming a file to a 
directory is not allowed. So rename internally converts the "logical name" to a 
file name, and dev: [dir] subdir is the most reasonable conversion it can perform. 


This new feature switch has a side effect of causing rename to a directory to take 
precedence over rename to a file. Consider this example: 


rename ( "filel.ext", "dir2" ) /* dir2 is not a logical */ 


With DECC$RENAME_ALLOW_DIR disabled, this example results in dir2.ext, 
regardless of whether or not subdirectory [.dir2] exists. 


With DECC$RENAME_ALLOW_DIR enabled, this example results in dir2.ext 
only if subdirectory [.dir2] does not exist. If subdirectory [.dir2] does exist, 
the result is [.dir2]filel.ext. 


Note 


If DECC$RENAME_NO_INHERIT is enabled, UNIX compliant behavior 
is expected, so DECC$RENAME_ALLOW_DIR is ignored, and renaming 
a file to a directory is not allowed. 


DECC$SELECT_IGNORES_INVALID_FD 

With DECC$SELECT_IGNORES_INVALID_FD enabled, select fails with errno 
set to EBADF when an invalid file descriptor is specified in one of the descriptor 
sets. 


With DECC$SELECT_IGNORES_INVALID_FD disabled, select ignores invalid 
file descriptors. 
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DECC$STDIO_CTX_EOL 
With DECC$STDIO_CTX_EOL enabled, writing to stdout and stderr for stream 
access is deferred until a terminator is seen or the buffer is full. 


With DECC$STDIO_CTX_EOL disabled, each fwrite generates a separate write, 
which for mailbox and record files generates a separate record. 


DECC$STREAM_PIPE 
With DECC$STREAM_PIPE enabled, the C RTL pipe function uses the more 
UNIX compatible stream I/O. 


With DECC$STREAM_PIPE disabled, pipe uses the OpenVMS legacy record I/O. 
This is the default. 


DECC$STRTOL_ERANGE 
With DECC$STRTOL_ERANGE enabled, the strtol behavior for an ERANGE 
error is corrected to consume all remaining digits in the string. 


With DECC$STRTOL_ERANGE disabled, the legacy behavior of leaving the 
pointer at the failing digit is preserved. 


DECC$THREAD_DATA_AST_SAFE 

The C RTL has a mode that allocates storage for thread-specific data allocated by 
threads at non-AST level separate for data allocated for ASTs. In this mode, each 
access to thread-specific data requires a call to LIB$AST_IN_PROG, which can 
add significant overhead when accessing thread-specific data in the C RTL. 


The alternate mode protects thread-specific data only if another function has it 
locked. This protects data that is in use within the C RTL, but does not protect 
the caller from an AST changing the data pointed to. 


This latter mode is now the C RTL default for the strtok, ecvt, and fevt 
functions. 


You can select the legacy AST safe mode by enabling DECC$THREAD_DATA_ 
AST_SAFE. 


DECC$TZ_CACHE_SIZE 
DECC$TZ_CACHE_SIZE specifies the number of time zones that can be held in 
memory. 


Default: 2 

Maximum: 2147483647 

DECCS$UMASK 

DECC$UMASK specifies the default value for the permission mask umask. By 


default, a parent C program sets the umask from the RMS default permissions for 
the process. A child process inherits the parent’s value for umask. 


To enter the value as an octal value, add the leading zero; otherwise, it is 
translated as a decimal value. For example: 


$ DEFINE DECCSUMASK 026 

Maximum: 0777 

DECCS$UNIX_LEVEL 

With the DECC$UNIX_LEVEL logical name, you can manage multiple C RTL 


feature logical names at once. By setting a value for DECC$UNIX_LEVEL from 
1 to 100, you determine the default value for groups of feature logical names. The 
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value you set has a cumulative effect: the higher the value, the more groups that 
are affected. Setting a value of 20, for example, enables all the feature logicals 
associated with a DECC$UNIX_LEVEL of 20, 10, and 1. 


The principal logical names affecting UNIX like behavior are grouped as follows: 


1 General corrections 

10 Enhancements 

20 UNIX style file names 

30 UNIX style file attributes 
90 


Full UNIX behavior - No concessions to OpenVMS 


Level 30 is appropriate for UNIX like programs such as BASH and GNV. 
The DECC$UNIX_LEVEL values and associated groups of affected feature logical 


names are: 


General Corrections 


DECCSFIXED LENGTH SEEK TO EOF 


DECCSPOSIX SEEK STREAM FILE 
DECCSSELECT IGNORES INVALID FD 
DECCSSTRTOL_ERANGE 
DECCSVALIDATE SIGNAL IN KILL 


General Enhancements 


DECCSARGV_PARSE STYLE 
DECCSEFS CASE PRESERVE 
DECCSSTDIO CTX EOL 
D 
D 


ECCS$PIPE BUFFER _SIZE 
ECCSUSE_RAB64 


UNI 


ta 


style file na 


DECCSDISABLE TO 
DECCSEFS CHARSET 

DECCSFILENAME UNIX NO VERSION 
DECCSFILENAME UNIX REPORT 
D 
D 
D 


es 


ECCSREADDIR_DROPDOTNOTYPE 
ECCSRENAME NO INHERIT 
ECCSGLOB UNIX STYLE 


like 


UNIX file attributes 


DECCSEFS FILE TIMESTAMPS 

DECCSEXEC_FILEATTR_ INHERITANCE 
DECCSFILE OWNER_UNIX 
D 
D 


ECCSFILE PERMISSION UNIX 
ECCSFILE SHARING 


compliant behavior 


DECCSFILENAME UNIX ONLY 
DECCS$POSIX STYLE UID 
DECCSUSE_JPI$ CREATOR 
DECCSDETACHED CHILD PROCESS 


1 


1 
1 
1 
1 


1 
1 
1 


(DECCSUNIX LEVEL 1) 


(DECCSUNIX LEVEL 10) 


4096 


al 


1 


1 
1 
1 
1 


1 


1 
1 
1 


(DECCSUNIX LEVEL 20) 
VMS LOGNAME TRANSLATION 1 


(DECCSUNIX LEVEL 30) 


(DECCSUNIX LEVEL 90) 


Notes 


e Defining a logical name for an individual feature logical supersedes 
the default value established by DECC$UNIX_LEVEL for that 


feature. 


1-42 Introduction 


e Future revisions of the C RTL may add new feature logicals to a given 
DECC$UNIX_LEVEL. For applications that specify that UNIX level, 
the effect is to enable those new feature logicals by default. 


DECCS$UNIX_PATH_BEFORE_LOGNAME 

With DECC$UNIX_PATH_BEFORE_LOGNAME enabled, when translating a 
UNIX file name not starting with a leading slash (/), an attempt is made to match 
this to a file or directory in the current directory. If this is not found and the 
name is valid as a logical name in an OpenVMS file name, an attempt is made to 
translate the logical name and, if found, is used as part of the resulting file name. 


Enabling DECC$UNIX_PATH_BEFORE_LOGNAME overrides the setting for 
DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION. 


DECC$USE_JPI$_CREATOR 

When enabled, DECC$USE_JPI$_CREATOR determines the parent process ID 
in getppid by calling $GETJPI using item JPI$_CREATOR instead of JPI$_ 
OWNER. 


This feature is only available on systems supporting POSIX style session 
identifiers. 


DECCS$USE_RAB64 
With DECC$USE_RAB64 enabled, open functions allocate a RAB64 structure 
instead of the traditional RAB structure. 


This provides latent support for file buffers in 64-bit memory. 


DECCS$VALIDATE_SIGNAL_IN_KILL 

With DECC$VALIDATE_SIGNAL_IN_KILL enabled, a signal value that is in the 
range 0 to _SIG_MAX but is not supported by the C RTL generates an error with 
errno set to EINVAL, which makes the behavior the same as for raise. 


With this logical name disabled, validation of signals is restricted to checking 
that the signal value is in the range 0 to _SIG_MAX. If sys$sigprc fails, errno is 
set based on sys$sigprc exit status. 


DECC$V62_RECORD_GENERATION 
OpenVMS Versions 6.2 and higher can output record files using different rules. 


With DECC$V62_RECORD_GENERATION enabled, the output mechanism 
follows the rules used for OpenVMS Version 6.2. 


DECCS$WRITE_SHORT_RECORDS 

The DECC$WRITE_SHORT_RECORDS feature logical supports a previous 
change to the fwrite function (to accommodate writing records with size less 
than the maximum record size), while retaining the legacy way of writing records 
to a fixed-length file as the default behavior: 


With DECC$WRITE_SHORT_RECORDS enabled, short-sized records (records 
with size less than the maximum record size) written at EOF are padded 
with zeros to align records on record boundaries. This is the behavior seen in 
OpenVMS Version 7.3-1 and some ACRTL ECOs of that time period. 


With DECC$WRITE_SHORT_RECORDS disabled, the legacy behavior of writing 
records with no padding is implemented. This is the recommended and default 
behavior. 
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DECC$XPG4_STRPTIME 

XPG5 support for strptime introduces pivoting year support so that years in the 
range 0 to 68 are in the 21st century, and years in the range 69-99 are in the 
20th century. 


With DECC$XPG4_STRPTIME enabled, XPG5 support for the pivoting year is 
disabled and all years in the range 0 to 99 are in the current century. 


1.7 32-Bit UIDs/GIDs and POSIX Style Identifiers 


Where supported in versions of the OpenVMS operating system, POSIX style 
identifiers refers to the User Identifier (UID), Group Identifier (GID), and Process 
Group. The scope includes real and effective identifiers. 


The support for POSIX style identifiers in the HP C RTL requires 32-bit user and 
group ID support and also depends on features in the base version of OpenVMS. 
POSIX style IDs are supported by OpenVMS Version 7.3-2 and higher. 


To use POSIX style identifiers on OpenVMS versions that support them requires 
applications to be compiled for 32-bit UID/GID. On OpenVMS versions where 
32-bit UID/GID is the default, the user or application must still enable POSIX 
style IDs by defining the DECC$POSIX_STYLE_UID feature logical name: 


$ DEFINE DECCSPOSIX_STYLE UID ENABLE 


With POSIX style IDs enabled, at compile time you can selectively invoke the 
traditional (UIC-based) definition for an individual function by explicitly calling 
it by its decc$-prefixed entry point (as opposed to the decc$__long gid -prefixed 
entry point, which provides the POSIX style behavior). 


To disable POSIX style IDs: 
$ DEFINE DECCSPOSIX_ STYLE UID DISABLE 


OpenVMS Version 7.3-2 and higher supports POSIX style IDs as well as 32-bit 
UID/GIDs. When an application is compiled to use 32-bit UID/GIDs, the UID and 
GID are derived from the UIC as in previous versions of the operating system. 

In some cases, such as with the getgroups function, more information may be 
returned when the application supports 32-bit GIDs. 


To compile an application for 16-bit UID/GID support on systems that by default 
use 32-bit UIDs/GIDs, define the .DDECC_SHORT_GID_T macro to 1. 


1.8 Input and Output on OpenVMS Systems 


After you learn how to link with the HP C RTL and call HP C functions and 
macros, you can use the HP C RTL for its primary purpose: input/output (I/O). 


Since every system has different methods of I/O, familiarize yourself with the 
OpenVMS specific methods of file access. In this way, you will be equipped 
to predict functional differences when porting your source program from one 
operating system to another. 


Figure 1-2 shows the I/O methods available with the HP C RTL. The OpenVMS 
system services communicate directly with the OpenVMS operating system, so 
they are closest to the operating system. The OpenVMS Record Management 
Services (RMS) functions use the system services, which manipulate the operating 
system. The HP C Standard I/O and UNIX I/O functions and macros use the 
RMS functions. Since the HP C RTL Standard I/O and UNIX I/O functions and 


1-44 Introduction 


macros must go through several layers of function calls before the system is 
manipulated, they are furthest from the operating system. 


Figure 1-2 I/O Interface from C Programs 
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The C programming language was developed on the UNIX operating system, and 
the Standard I/O functions were designed to provide a convenient method of I/O 
that would be powerful enough to be efficient for most applications, and also be 
portable so that the functions could be used on any system running C language 
compilers. 


The HP C RTL adds functionality to this original specification. Since, as 
implemented in the HP C RTL, the Standard I/O functions recognize line 
terminators, the HP C RTL Standard I/O functions are particularly useful for 
text manipulation. The HP C RTL also implements some of the Standard I/O 
functions as preprocessor-defined macros. 


In a similar manner, the UNIX I/O functions originally were designed to provide 

a more direct access to the UNIX operating systems. These functions were meant 
to use a numeric file descriptor to represent a file. A UNIX system represents all 
peripheral devices as files to provide a uniform method of access. 


The HP C RTL adds functionality to the original specification. The UNIX I/O 
functions, as implemented in HP C, are particularly useful for manipulating 
binary data. The HP C RTL also implements some of the UNIX I/O functions as 
preprocessor-defined macros. 


The HP C RTL includes the Standard I/O functions that should exist on all C 
compilers, and also the UNIX I/O functions to maintain compatibility with as 
many other implementations of C as possible. However, both Standard I/O and 
UNIX I/O use RMS to access files. To understand how the Standard I/O and 
UNIX I/O functions manipulate RMS formatted files, learn the fundamentals 
of RMS. See Section 1.8.1 for more information about Standard I/O and UNIX 
I/O in relationship to RMS files. For an introduction to RMS, see the Guide to 
OpenVMS File Applications. 


Before deciding which method is appropriate for you, first ask this question: Are 
you concerned with UNIX compatibility or with developing code that will run 
solely under the OpenVMS operating system? 


e If UNIX compatibility is important, you probably want to use the highest 
levels of I/O—Standard I/O and UNIX I/O—because that level is largely 
independent of the operating system. Also, the highest level is easier to learn 
quickly, an important consideration if you are a new programmer. 
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e If UNIX compatibility is not important to you or if you require the 
sophisticated file processing that the Standard I/O and UNIX I/O methods do 
not provide, you might find RMS desirable. 


If you are writing system-level software, you may need to access the OpenVMS 
operating system directly through calls to system services. For example, you 
may need to access a user-written device driver directly through the Queue I/O 
Request System Service ($QIO). To do this, use the OpenVMS level of I/O; this 
level is recommended if you are an experienced OpenVMS programmer. For 
examples of programs that call OpenVMS system services, see the HP C User’s 
Guide for OpenVMS Systems. 


You may never use the RMS or the OpenVMS system services. The Standard I/O 
and UNIX I/O functions are efficient enough for a large number of applications. 
Figure 1-3 shows the dependency of the Standard I/O and the UNIX I/O functions 
on RMS, and the various methods of I/O available to you. 


Figure 1-3 Mapping Standard I/O and UNIX I/O to RMS 
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1.8.1 RMS Record and File Formats 


To understand the capabilities and the restrictions of the Standard I/O and UNIX 
I/O functions and macros, you need to understand OpenVMS Record Management 
Services (RMS). 


RMS supports the following file organizations: 
e Sequential 
e Relative 


e Indexed 
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Sequential files have consecutive records with no empty records in between; 
relative files have fixed-length cells that may or may not contain a record; and 
indexed files have records that contain data, carriage-control information, and 
keys that permit various orders of access. 


The HP C RTL functions can access only sequential files. If you wish to use the 
other file organizations, you must use the RMS functions. For more information 
about the RMS functions, see the HP C User’s Guide for OpenVMS Systems. 


RMS is not concerned with the contents of records, but it is concerned about the 
record format, which is the way a record physically appears on the recording 
surface of the storage medium. 


RMS supports the following record formats: 
e =6Fixed-length 

e = Variable-length 

e Variable with fixed-length control (VFC) 
e Stream 


You can specify a fixed-length record format at the time of file creation. This 
means that all records occupy the same amount of space in the file. You cannot 
change the record format once you create the file. 


The length of records in variable-length, VFC, and stream file formats can 
vary up to a maximum size that must be specified when you create the file. 
With variable-length record or VFC format files, the size of the record is held 
in a header section at the beginning of the data record. With stream files, 
RMS terminates the records when it encounters a specific character, such as a 
carriage-control or line-feed character. Stream files are useful for storing text. 


RMS allows you to specify carriage-control attributes for records in a file. Such 
attributes include the implied carriage-return or the Fortran formatted records. 
RMS interprets these carriage controls when the file is output to a terminal, a 
line printer, or other device. The carriage-control information is not stored in the 
data records. 


By default, files inherit the RMS record format, maximum record size and 
record attributes, from the previous version of the file, if one exists; to an 
OpenVMS system programmer, the inherited attributes are known as FAB$B_ 
RFM, FAB$W_MRS and FAB$B_RAT. If no previous versions exist, the newly 
created file defaults to stream format with line-feed record separator and implied 
carriage-return attributes. (This manual refers to this type of file as a stream 
file.) You can manipulate stream files using the Standard I/O and the UNIX I/O 
functions of the HP C RTL. When using these files and fixed-record files with no 
carriage control, there is no restriction on the ability to seek to any random byte 
of the file using the fseek or the lseek functions. However, if the file has one of 
the other RMS record formats, such as variable-length record format, then these 
functions, due to RMS restrictions, can seek only to record boundaries. Use the 
default VAX stream format unless you need to create or access files to be used 
with other VAX languages or utilities. 
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1.8.2 Access to RMS Files 


RMS sequential files can be opened in record mode or stream mode. By default, 
STREAM _LF files are opened in stream mode; all other file types are opened in 
record mode. When opening a file, you can override these defaults by specifying 
the optional argument "ctx=rec" to force record mode, or "ctx=stm" to force stream 
mode. RMS relative and indexed files are always opened in record mode. The 
access mode determines the behavior of various I/O functions in the HP C RTL. 


One of the file types defined by RMS is an RMS—11 stream format file, 
corresponding to a value of FAB$C_STM for the record format. The definition 

of this format is such that the RMS record operation SYS$GET removes leading 
null bytes from each record. Because this file type is processed in record mode 
by the HP C RTL, it is unsuitable as a file format for binary data unless it is 
explicitly opened with "ctx=stm", in which case the raw bytes of data from the file 
are returned. 


Note 


In OpenVMS Version 7.0 the default LRL value on stream files was 
changed from 0 to 32767. This change caused significant performance 
degradation on certain file operations such as sort. 


This is no longer a problem. The HP C RTL now lets you define the 
logical DECC$DEFAULT_LRL to change the default record-length value 
on stream files. 


The HP C RTL first looks for this logical. If it is found and it translates to 
a numeric value between 0 and 32767, that value is used for the default 
LRL. 


To restore the behavior prior to OpenVMS Version 7.0, enter the following 
command: 


$ DEFINE DECCSDEFAULT LRL 0 


1.8.2.1 Accessing RMS Files in Stream Mode 


Stream access to RMS files is done with the block I/O facilities of RMS. 
Stream input is performed from RMS files by passing each byte of the on-disk 
representation of the file to your program. Stream output to RMS files is done 
by passing each byte from your program to the file. The HP C RTL performs no 
special processing on the data. 


When opening a file in stream mode, the HP C RTL allocates a large internal 
buffer area. Data is read from the file using a single read into the buffer area 
and then passing the data to your program as needed. Data is written to the file 
when the internal buffer is full or when the fflush function is called. 


1.8.2.2 Accessing RMS Record Files in Record Mode 
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Record access to record files is done with the record I/O facilities of RMS. The 
HP C RTL emulates a byte stream by translating carriage-control characters 
during the process of reading and writing records. Random access is allowed 
to all record files, but positioning (with fseek and lseek) must be on a record 
boundary for VFC files, variable record files, or files with non-null carriage 
control. Positioning a record file causes all buffered input to be discarded and 
buffered output to be written to the file. 
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Record input from RMS record files is emulated by the HP C RTL in two steps: 


1. The HP C RTL reads a logical record from the file. 


If the record format is variable length with fixed control (RFM = VFC), and 
the record attributes are not print carriage control (RAT is not PRN), then the 
HP C RTL concatenates the fixed-control area to the beginning of the record. 


2. The HPC RTL expands the record to simulate a stream of bytes by 
translating the record’s carriage-control information (if any). 


In RMS terms, the HP C RTL translates the record’s carriage-control information 
using one of the following methods: 


e Ifthe record attribute is implied carriage control (RAT = CR), then the HP C 
RTL appends a new-line character to the record. 


This new-line character is considered an integral part of the record, which 
means for example, that it can be obtained by the fgetc function and is 
considered a line terminator by the fgets function. Since fgets reads the file 
up to the new-line character, for RAT=CR files this function cannot retrieve a 
string that crosses the record boundaries. 


e Ifthe record attributes are print carriage control (RAT = PRN), then the 
HP C RTL expands and concatenates the prefix and postfix carriage controls 
before and after the record. 


This translation is done according to rules specified by RMS, with one 
exception: if the prefix character is x01 and the postfix character is x8D, 
then nothing is attached to the beginning of the record and a single new-line 
character is attached to the end of it. This is done because this prefix/postfix 
combination is normally used to represent a line. 


e Ifthe record attributes are Fortran carriage control (RAT = FTN), then the 
HP C RTL removes the initial control byte and attaches the appropriate 
carriage-control characters before and after the data as defined by RMS, with 
the exception of the space and default carriage-control characters. In these 
cases, which are used to represent a line, the HP C RTL appends a single 
new-line character to the data. 


The mapping of Fortran carriage-control can be disabled by using "ctx=nocvt". 


e Ifthe record attributes are null (RAT = NONE) and the input is coming from 
a terminal, then the HP C RTL appends the terminating character to the 
record. If the terminator is a carriage return or Ctrl/Z, then HP C translates 
the character to a new-line character (\n). 


If the input is coming from a nonterminal file, then the HP C RTL passes 
the record unchanged to your program with no additional prefix or postfix 
characters. 


As you read from the file, the HP C RTL delivers a stream of bytes resulting from 
the translations. Information that is not read from an expanded record by one 
function call is delivered on the next input function call. 


The HP C RTL performs record output to RMS record files in two steps. 


The first part of the record output emulation is the formation of a logical record. 
As you write bytes to a record file, the emulator examines the information being 
written for record boundaries. The handling of information in the byte stream 
depends on the attributes of the destination file or device, as follows: 
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For all files, if the number of output bytes is greater than the internal buffer 
allocated by the HP C RTL, a record is output. 


For files with fixed record length (RFM = FIX) or for files opened with 
"ctx=bin" or "ctx=xplct", a record is output only when the internal buffer 
is filled or when the flush function is called. 


For files with STREAM_CR record format (RFM = STMCR), the HP C RTL 
outputs a record when it encounters a carriage-return character (\r). 


For files with STREAM record format (RFM = STM) the HP C RTL outputs a 
record when it encounters a new-line (\n), form feed (\f), or vertical tab (\v) 
character. 


For all other file types, the HP C RTL outputs a record when it encounters a 
new-line (\n) character. 


The second part of record output emulation is to write the logical record formed 
during the first step. The HP C RTL forms the output record as follows: 
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If the record attribute is carriage control (R AT = CR), and if the logical 
record ends with a new-line character (\n), the HP C RTL drops the new-line 
character and writes the logical record with implied carriage control. 


If the record attribute is print carriage control (RAT = PRN), then the HP C 
RTL writes the record with print carriage control according to the rules 
specified by RMS. If the logical record ends with a single new-line character 
(\n), the HP C RTL maps the new-line character to an x01 prefix and x8D 
postfix character. This is the reverse of the translation for record input files 
with print carriage-control attributes. 


If the record attributes are Fortran carriage control (RAT = FTN), then the 
HP C RTL removes any prefix and/or postfix carriage-control characters and 
concatenates a single carriage-control byte to the beginning of the record as 
defined by RMS, with one exception: If the output record ends in a new-line 
character (\n), the HP C RTL will remove the new-line character and use the 
space carriage-control byte. This is the reverse of the translation for record 
input files with Fortran carriage-control attributes. 


The mapping of Fortran carriage-control can be disabled by using "ctx=nocvt". 


If the logical record is to be written to a terminal device and the last character 
of the record is a new-line character (\n) the HP C RTL replaces the new-line 
character with a carriage-return (\r), and attaches a line-feed character (\n) 
to the front of the record. The HP C RTL then writes out the record with no 
carriage control. 


If the output file record format is variable length with fixed control (RFM = 
VFC), and the record attributes do not include print carriage control (RAT is 
not PRN), then the HP C RTL takes the beginning of the logical record to be 
the fixed-control header, and reduces the number of bytes written out by the 
length of the header. These bytes are then used to construct the fixed-control 
header. If there are too few bytes in the logical record, an error is signaled. 


1.8.2.2.1 Accessing Variable-Length or VFC Record Files in Record Mode 
When you access a variable-length or VFC record file in record mode, many I/O 
functions behave differently than they would if they were being used with stream 
mode. This section describes these differences. 


In general, the new-line character (\n) is the record separator for all record 
modes. On output, when a new-line character is encountered, a record is 
generated unless you specify an optional argument (such as "ctx=bin" or 
"ctx=xplct") that affects the interpretation of new lines. 


The read and decc$record_read functions always read at most one record. The 
write and decc$record_write functions always generate at least one record. 


decc$record_read and deccSrecord_write are equivalent, respectively, to read 
and write, except that they work with file pointers rather than file descriptors. 


Unlike the read function, which reads at most one record, the fread function 
can span records. Rather than read number_items records (where number_items 
is the third parameter to fread), fread tries to read the number of bytes equal 
to number_items x size_of_item (where size_of_item is the second parameter to 
fread). The value returned by fread is equal to the number of bytes read divided 
by size_of_item. 


However, the fwrite function always generates at least number_items records. 


The fgets and gets functions read to either a new-line character or a record 
boundary. 


The fflush function always generates a record if there is unwritten data in the 
buffer. The same is true of close, fclose, fseek, lseek, rewind, and fsetpos, all 
of which perform implicit fflush functions. 


A record is also generated whenever an attempt is made to write more characters 
than allowed by the maximum record size. 


For more information on these functions, see the Reference Section. 


1.8.2.2.2 Accessing Fixed-Length Record Files in Record Mode When 
accessing a fixed-length record file in record mode, the I/O functions generally 
behave as described in Section 1.8.2.2.1. 


The write, fwrite, and decc$record_write functions will fail if given a record 
size that is not an integral multiple of the maximum record size, unless the file 
was opened with the "ctx=xplct" optional argument specified. All other output 
functions will generate records at every nth byte, where n is the maximum record 
s1zZe. 


If a new record is forced by fflush, the data in the buffer is padded to the 
maximum record size with null characters. 


Note 


This padding can cause problems for programs that seek to the end-of- 
file. For example, if a program were to append data to a file, then seek 
backwards in the file (causing an fflush to occur), and then seek to the 
end-of-file again, a zero-filled "hole" will have been created between the 
previous end-of-file and the new end-of-file if the previous end-of-file was 
not on a record boundary. 
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1.8.2.3 Example—Difference Between Stream Mode and Record Mode 
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Example 1-1 demonstrates the difference between stream mode and record mode 


access. 


Example 1-1 Differences Between Stream Mode and Record Mode Access 


/* CHAP 1 STREAM RECORD.C */ 


/* This program demonstrates the difference between */ 
/* record mode and stream mode input/output. */ 


#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 


void process records(const char *fspec, FILE * fp); 


main () 


FILE *£p; 


fp = fopen("example-fixed.dat", "w", "rfm=fix", "mrs=40", "rat=none") ; 


if (fp == NULL) 
perror ("example-fixed") ; 
exit (EXIT_FAILURE) ; 


printf ("Record mode\n") ; 
process records ("example-fixed.dat", fp); 
fclose(fp) ; 


printf ("\nStream mode\n") ; 

fp = fopen("example-streamlf.dat", "w") ; 

if (fp == NULL) 
perror ("example-streamlf") ; 
exit (EXIT_FAILURE) ; 


—! 


process records ("example-streamlf.dat", fp); 
fclose(fp) ; 


} 


void process records(const char *fspec, FILE * fp) 


int i, 
sts; 
char buffer [40]; 


/* Write records of all 1’s, all 2’s and all 3’s */ 
for (i = 0; i < 3; i++) 
memset (buffer, ‘1’ + i, 40); 
sts = fwrite(buffer, 40, 1, fp); 
if (sts != 1) 
perror ("fwrite") ; 
exit (EXIT_FAILURE) ; 
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(continued on next page) 


Example 1-1 (Cont.) Differences Between Stream Mode and Record Mode 


Access 

/* Rewind the file and write 10 characters of A’s, then 10 B’s, */ 
/* then 10 C's. */ 
[* */ 
/* For stream mode, each fwrite call outputs 10 characters */ 
/* and advances the file position 10 characters */ 
/* characters. */ 
/* */ 
/* For record mode, each fwrite merges the 10 characters into */ 
/* the existing 40-character record, updates the record and */ 
/* advances the file position 40 characters to the next record. */ 
rewind (fp) ; 


for (i = 0; 1 < 3; i++) { 
memset (buffer, ‘A’ + i, 10); 
sts = fwrite(buffer, 10, 1, fp); 
if (sts != 1) { 
perror ("fwrite2") ; 
exit (EXIT_FAILURE) ; 


} 


/* Now reopen the file and output the records. */ 


fclose(fp) ; 
fp = fopen(fspec, "r"); 
for (i = 0; 1 < 3; i++) 
sts = fread(buffer, 40, 1, fp); 
Lf -(st¢ = 1) 
perror ("fread") ; 
printf ("%.40s\n", buffer) ; 


} 


return; 


} 


Running this program produces the following output: 


Record Mode 

AAAAAAAAAAI11111111111111111111111111111 
BBBBBBBBBB222222222222222222222222222222 
CCCCCCCCCC3 33333333333333333333333333333 


Stream mode 

AAAAAAAAAABBBBBBBBBBCCCCCCCCCC1111111111 
2222222222222 222222222222222222222222222 
3333333333333333333333333333333333333333 


1.9 Specific Portability Concerns 


One of the last tasks in preparing to use the HP C RTL, if you are going to 

port your source programs across systems, is to be aware of specific differences 
between the HP C RTL and the run-time libraries of other implementations of 
the C language. This section describes some of the problems that you might 
encounter when porting programs to and from an OpenVMS system. Although 
portability is closely tied to the implementation of the HP C RTL, this section also 
contains information on the portability of other HP C for OpenVMS constructs. 
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The HP C RTL provides ANSI C defined library functions as well as many 
commonly available APIs and a few OpenVMS extensions. See Section 1.5 

for specific standards, portions of which are implemented by the HP C RTL. 
Attempts have been made to maintain complete portability in functionality 
whenever possible. Many of the Standard I/O and UNIX I/O functions and 
macros contained in the HP C RTL are functionally equivalent to those of other 
implementations. 


The RTL function and macro descriptions elaborate on issues presented in this 
section and describe concerns not documented here. 


The following list documents issues of concern if you wish to port C programs to 
the OpenVMS environment: 


e HPC for OpenVMS Systems does not implement the global symbols end, 
edata, and etext. 


e There are differences in how OpenVMS and UNIX systems lay out virtual 
memory. In some UNIX systems, the address space between 0 and the break 
address is accessible to your program. In OpenVMS systems, the first page of 
memory is not accessible. 


For example, if a program tries to reference location 0 on an OpenVMS 
system, a hardware error (ACCVIO) is returned and the program terminates 
abnormally. OpenVMS systems reserve the first page of address space to 
catch incorrect pointer references, such as a reference to a location pointed to 
by a null pointer. For this reason, some existing programs that run on some 
UNIX systems may fail and you should modify them, as necessary. (Tru64 
UNIX and OpenVMS, however, are compatible in this regard.) 


e Some C programmers code all external declarations in #include files. Then, 
specific declarations that require initialization are redeclared in the relevant 
module. This practice causes the HP C compiler to issue a warning message 
about multiply declared variables in the same compilation. One way to avoid 
this warning is to make the redeclared symbols extern variables in the 
#include files. 


e HPC does not support asm calls on OpenVMS VAX and I64 systems. They 
are supported on OpenVMS Alpha systems. See the HP C User’s Guide for 
OpenVMS Systems for more information on intrinsic functions. 


e Some C programs call the counted string functions strcmpn and strcpyn. 
These names are not used by HP C for OpenVMS Systems. Instead, you 
can define macros that expand the strcmpn and strcpyn names into the 
equivalent, ANSI-compliant names strncmp and strncpy. 


e The HP C for OpenVMS compiler does not support the following initialization 
form: 


int foo 123; 
Programs using this form of initialization must be changed. 


e HPC for OpenVMS Systems predefines several compile-time macros such as 
vax, _ alpha, 1a64 32BITS, ovms, vaxc, VMS VER, DECC VER, 
D FLOAT, G FLOAT, IEEE FLOAT, X FLOAT, and others. These 
predefined macros are useful for programs that must be compatible on other 
machines and operating systems. For more information, see the predefined 
macro chapter of the HP C User’s Guide for OpenVMS Systems. 


Introduction 


The ANSI C language does not guarantee any memory order for the variables 
in a declaration. For example: 


int a, b, c; 


Depending on the type of external linkage requested, extern variables in a 
program may be treated differently using HP C on OpenVMS systems than 
they would on UNIX systems. See the HP C User’s Guide for OpenVMS 
Systems for more information. 


The dollar sign ($) is a legal character in HP C for OpenVMS identifiers, and 
can be used as the first character. 


The ANSI C language does not define any order for evaluating expressions 
in function parameter lists or for many kinds of expressions. The way in 
which different C compilers evaluate an expression is only important when 
the expression has side effects. Consider the following examples: 


a{i] = it; 
x = func_y() + func_z(); 
f (p++, ptt) 


Neither HP C nor any other C compiler can guarantee that such expressions 
evaluate in the same order on all C compilers. 


The size of a HP C variable of type int is 32 bits on OpenVMS systems. You 
will have to modify programs that are written for other machines and that 
assume a different size for a variable of type int. A variable of type long is 
the same size (32 bits) as a variable of type int. 


The C language defines structure alignment to be dependent on the machine 
for which the compiler is designed. On OpenVMS VAX systems, HP C aligns 
structure members on byte boundaries, unless #pragma member_alignment is 
specified. On OpenVMS Alpha systems, HP C aligns structure members on 

natural boundaries, unless #pragma nomember alignment is specified. Other 
implementations may align structure members differently. 


References to structure members in HP C cannot be vague. For more 
information, see the HP C Language Reference Manual. 


Registers are allocated based upon how often a variable is used, but the 
register keyword gives the compiler a strong hint that you want to place a 
particular variable into a register. Whenever possible, the variable is placed 
into a register. Any scalar variable with the storage class auto or register 
can be allocated to a register as long as the variable’s address is not taken 
with the ampersand operator (& ) and it is not a member of a structure or 
union. 


1.9.1 Reentrancy 


The HP C RTL supports an improved and enhanced reentrancy. The following 
types of reentrancy are supported: 


AST reentrancy uses the _BBSSI built-in function to perform simple locking 
around critical sections of RTL code, but it may also disable asynchronous 
system traps (ASTs) in locked regions of code. This type of locking should be 
used when AST code contains calls to HP C RTL I/O routines. 


Failure to specify AST reentrancy might cause I/O routines to fail, setting 
errno to EALREADY. 
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e MULTITHREAD reentrancy is designed to be used in threaded programs 
such as those that use the POSIX threads library. It performs threads locking 
and never disables ASTs. The POSIX Threads library must be available on 
your system to use this form of reentrancy. 


e TOLERANT reentrancy uses the _BBSSI built-in function to perform simple 
locking around critical sections of RTL code, but ASTs are not disabled. This 
type of locking should be used when ASTs are used and must be delivered 
immediately. 


e NONE gives optimal performance in the HP C RTL, but does absolutely 
no locking around critical sections of RTL code. It should only be used in 
a single-threaded environment when there is no chance that the thread of 
execution will be interrupted by an AST that would call the HP C RTL. 


For nonthreaded processes, the default reentrancy type is TOLERANT. When 
the threads library is loaded, the reentracy level is implicitly set to C$C_ 
MULTITHREAD, and the application cannot change it after that. 


You can set the reentrancy type by compiling with the /REENTRANCY command- 
line qualifier or by calling the decc$set_reentrancy function. This function must 
be called exclusively from non-AST level. 


When programming an application using multiple threads or ASTs, consider three 
classes of functions: 


e Functions with no internal data 
e Functions with thread-local internal data 
e Functions with processwide internal data 


Most functions have no internal data at all. For these functions, synchronization 
is necessary only if the parameter is used by the application in multiple threads 
or in both AST and non-AST contexts. For example, although the strcat function 
is ordinarily safe, the following is an example of unsafe usage: 


extern char buffer[100]; 
void routinel(char *data) { 
strceat( buffer, data ); 


If routinel executed concurrently in multiple threads, or if routinel is 
interrupted by an AST routine that calls it, the results of the strcat call are 
unpredictable. 


The second class of functions are those that have thread-local static data. 
Typically, these are routines in the library that return a string where the 
application is not permitted to free the storage for the string. These routines 
are thread-safe but not AST-reentrant. This means they can safely be called 
concurrently, and each thread will have its own copy of the data. They cannot be 
called from AST routines if it is possible that the same routine was executing in 
non-AST context. The routines in this class are: 


asctime stat 

ctermid strerror 

ctime strtok 

cuserid VAXCSESTABLISH 

gmt ime the errno variable 
localtime westok 

perror 
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All the socket functions are also included in this list if the TCP/IP product in use 
is thread-safe. 


The third class of functions are those that affect processwide data. These 
functions are neither thread-safe nor AST-reentrant. For example, sigsetmask 
establishes the processwide signal mask. Consider a routine like the following: 


void update data 
base () 


int old_mask; 


old_ mask = sigsetmask( 1 << (SIGINT - 1)); 
/* Do work here that should not be aborted. */ 
sigsetmask( old_mask ); 


} 


If update_database was called concurrently in multiple threads, thread 1 might 
unblock SIGINT while thread 2 was still performing work that should not be 
aborted. 


The routines in this class are: 

e All the signal routines 

e All the exec routines 

e The exit, exit, nice, system, wait, getitimer, setitimer, and setlocale 


routines. 


Note 


Generally speaking, UTC-based time functions can affect in-memory time- 
zone information, which is processwide data. However, if the system time 
zone remains the same during the execution of the application (which is 
the common case) and the cache of time-zone files is enabled (which is the 
default), then the _r variant of the time functions asctime_r, ctime_r, 
gmtime_r and localtime_r is both thread-safe and AST-reentrant. 


If, however, the system time zone can change during the execution of 
the application or the cache of time-zone files is not enabled, then both 
variants of the UTC-based time functions belong to the third class of 
functions, which are neither thread-safe nor AST-reentrant. 


Some functions remain inherently nonthread-safe regardless of the reentrancy 
type. They are: 


execl exit 
execle exit 
execlp nice 
execv system 
execve vfork 
execvp 


Introduction 1-57 


1.9.2 Multithread Restrictions 


Mixing the multithread programming model and the OpenVMS AST 
programming model in the same application is not recommended. The application 
has no mechanism to control which thread gets interrupted by an AST. This can 
result in a resource deadlock if the thread holds a resource that is also needed 
by the AST routine. The following functions use mutexes. To avoid a potential 
resource deadlock, do not call them from AST functions in a multithreaded 
application. 


e All the I/O functions 

e All the socket functions 

e All the signal functions 

e vfork, exec, wait, system 

e catgets 

e set new handler (C++ only) 
e getenv 

e rand and srand 


e exit and exit 


e clock 
e nice 
e times 


e ctime, localtime, asctime, mktime 


1.10 64-Bit Pointer Support (ipa, ics 


This section is for application developers who need to use 64-bit virtual memory 
addressing on OpenVMS Alpha Version 7.0 or higher. 


OpenVMS Alpha 64-bit virtual addressing support makes the 64-bit virtual 
address space defined by the Alpha architecture available to both the OpenVMS 
operating system and its users. It also allows per-process virtual addressing for 
accessing dynamically mapped data beyond traditional 32-bit limits. 


The HP C Run-Time Library on OpenVMS Alpha Version 7.0 systems and higher 
includes the following features in support of 64-bit pointers: 


e Guaranteed binary and source compatibility of existing programs 

e No impact on applications that are not modified to exploit 64-bit support 
e Enhanced memory allocation routines that allocate 64-bit memory 

e Widened function parameters to accommodate 64-bit pointers 


e Dual implementations of functions that need to know the pointer size used by 
the caller 


e New information available to the DEC C Version 5.2 compiler or higher to 
seamlessly call the correct implementation 


e Ability to explicitly call either the 32-bit or 64-bit form of functions for 
applications that mix pointer sizes 
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e A single shareable image for use by 32-bit and 64-bit applications 


1.10.1 Using the HP C Run-Time Library 


The HP C Run-Time library on OpenVMS Alpha Version 7.0 systems and higher 
can generate and accept 64-bit pointers. Functions that require a second interface 
to be used with 64-bit pointers reside in the same object libraries and shareable 
images as their 32-bit counterparts. No new object libraries or shareable images 
are introduced. Using 64-bit pointers does not require changes to your link 
command or link options files. 


The HP C 64-bit environment allows an application to use both 32-bit and 
64-bit addresses. For more information about how to manipulate pointer sizes, 
see the /POINTER_SIZE qualifier and #pragma pointer size and #pragma 
required pointer size preprocessor directives in the HP C User’s Guide for 
OpenVMS Systems. 


The /POINTER_SIZE qualifier requires you to specify a value of 32 or 64. This 
value is used as the default pointer size within the compilation unit. You can 
compile one set of modules using 32-bit pointers and another set using 64-bit 
pointers. Care must be taken when these two separate groups of modules call 
each other. 


Use of the /POINTER_SIZE qualifier also influences the processing of HP C RTL 
header files. For those functions that have a 32-bit and 64-bit implementation, 
specifying /POINTER_SIZE enables function prototypes to access both functions, 
regardless of the actual value supplied to the qualifier. In addition, the value 
specified to the qualifier determines the default implementation to call during 
that compilation unit. 


The #pragma pointer size and #pragma required pointer size preprocessor 
directives can be used to change the pointer size in effect within a compilation 
unit. You can default pointers to 32-bit pointers and then declare specific pointers 
within the module as 64-bit pointers. You would also need to specifically call the 
_mallocé4 form of malloc to obtain memory from the 64-bit memory area. 


1.10.2 Obtaining 64-Bit Pointers to Memory 


The HP C RTL has many functions that return pointers to newly allocated 
memory. In each of these functions, the application owns the memory pointed to 
and is responsible for freeing that memory. 


Functions that allocate memory are: 


malloc 
calloc 
realloc 
strdup 


Each of these functions have a 32-bit and a 64-bit implementation. When the 
/POINTER_SIZE qualifier is used, the following functions can also be called: 


_malloc32, mallocé4 
_calloc32, callocé4 
_realloc32, realloc64 
_strdup32, strdup64 


When /POINTER_SIZE=32 is specified, all malloc calls default to _malloc32. 
When /POINTER_SIZE=64 is specified, all malloc calls default to _mallocé4. 
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Regardless of whether the application calls a 32-bit or 64-bit memory allocation 
routine, there is still a single free function. This function accepts either pointer 
size. 


Be aware that the memory allocation functions are the only ones that return 
pointers to 64-bit memory. All HP C RTL structure pointers returned to the 
calling application (such as a FILE, WINDOW, or DIR) are always 32-bit pointers. 
This allows both 32-bit and 64-bit callers to pass these structure pointers within 
the application. 


1.10.3 HP C Header Files 


The header files distributed with OpenVMS support 64-bit pointers. Each 
function prototype whose signature contains a pointer is constructed to indicate 
the size of the pointer accepted. 


A 32-bit pointer can be passed as an argument to functions that accept either a 
32-bit or 64-bit pointer for that argument. 


A 64-bit pointer, however, cannot be passed as an argument to a function that 
accepts a 32-bit pointer. Attempts to do this are diagnosed by the compiler with 
a MAYLOSEDATA message. The diagnostic message IMPLICITFUNC means the 
compiler can do no additional pointer-size validation for calls to that function. 

If this function is an HP C RTL function, refer to the reference section of this 
manual for the name of the header file that defines that function. 


You might find the following pointer-size compiler diagnostics useful: 


e =%CC-IMPLICITFUNC 


A function prototype was not found before using the specified function. The 
compiler and run-time system rely on prototype definitions to detect incorrect 
pointer-size usage. Failure to include the proper header files can lead to 
incorrect results and/or pointer truncation. 


e = %CC-MAYLOSEDATA 


A truncation is necessary to do this operation. The operation could be passing 
a 64-bit pointer to a function that does not support a 64-bit pointer in the 
given context. It could also be a function returning a 64-bit pointer to a 
calling application that is trying to store that return value in a 32-bit pointer. 


e %CC-MAYHIDELOSS 


This message (when enabled) helps expose real MAYLOSEDATA messages 
that are being suppressed because of a cast operation. To enable this warning, 
compile with the qualifier /‘WARNINGS=ENABLE=MAYHIDELOSS. 


1.10.4 Functions Affected 
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The HP C RTL accommodates applications that use only 32-bit pointers, only 
64-bit pointers, or combinations of both. To use 64-bit memory, you must, at a 
minimum, recompile and relink an application. The amount of source code change 
required depends on the application itself, calls to other run-time libraries, and 
the combinations of pointer sizes used. 


With respect to 64-bit pointer support, the functions in the HP C RTL fall into 
four categories: 


e Functions not impacted by choice of pointer size 
e Functions enhanced to accept either pointer size 


e Functions having a 32-bit and 64-bit implementation 
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e Functions that accept only 32-bit pointers 


From an application developer’s perspective, the first two types of functions are 
the easiest to use in either a single- or mixed-pointer mode. 


The third type requires no modifications when used in a single-pointer 
compilation, but might require source code changes when used in a mixed-pointer 
mode. 


The fourth type requires careful attention whenever 64-bit pointers are used. 


1.10.4.1 No Pointer-Size Impact 
The choice of pointer size has no impact on a function if its prototype contains 
no pointer-related parameters or return values. The mathematical functions are 
good examples of this. 


Even some functions in this category that do have pointers in their prototype are 
not impacted by pointer size. For example, strerror has the prototype: 


char * strerror (int error_number) ; 


This function returns a pointer to a character string, but this string is allocated 
by the HP C RTL. As a result, to support both 32-bit and 64-bit applications, 
these types of pointers are guaranteed to fit in a 32-bit pointer. 


1.10.4.2 Functions Accepting Both Pointer Sizes 
The Alpha architecture supports 64-bit pointers. The OpenVMS Alpha calling 
standard specifies that all arguments are actually passed as 64-bit values. Before 
OpenVMS Alpha Version 7.0, all 32-bit addresses passed to procedures were sign- 
extended into this 64-bit parameter. The called function declared the parameters 
as 32-bit addresses, which caused the compiler to generate 32-bit instructions 
(such as LDL) to manipulate these parameters. 


Many functions in the HP C RTL are enhanced to receive the full 64-bit address. 
For example, consider strlen: 


size_t strlen (const char *string) ; 


The only pointer in this function is the character-string pointer. If the caller 
passes a 32-bit pointer, the function works with the sign-extended 64-bit address. 
If the caller passes a 64-bit address, the function works directly with that address. 


The HP C RTL continues to have only a single entry point for functions in this 
category. There are no source-code changes required to add any of the four 
pointer-size options for functions of this type. The OpenVMS documentation 
refers to these functions as 64-bit friendly. 


1.10.4.3 Functions with Two Implementations 
There are many reasons why a function might need one implementation for 32-bit 
pointers and another for 64-bit pointers. Some of these reasons include: 


e The pointer size of the return value is the same size as the pointer size of one 
of the arguments. If the argument is 32 bits, the return value is 32 bits. If 
the argument is 64 bits, the return value is 64 bits. 


e One of the arguments is a pointer to an object whose size is pointer-size 
sensitive. To know how many bytes are being pointed to, the function must 
know if the code was compiled in 32-bit or 64-bit pointer-size mode. 
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e The function returns the address of dynamically allocated memory. The 
memory is allocated in 32-bit space when compiled for 32-bit pointers, and is 
allocated in 64-bit space when compiled for 64-bit pointers. 


From the application developer’s point of view, there are three function prototypes 
for each of these functions. The <string.h> header file contains many functions 
whose return value is dependent upon the pointer size used as the first argument 
to the function call. For example, consider the memset function. The header file 
defines three entry points for this function: 


void * memset (void *memory_ pointer, int character, size_t size); 
void * memset32 (void *memory pointer, int character, size_t size); 
void * memset64 (void *memory pointer, int character, size t size); 


The first prototype is the function that your application would currently call if 
using this function. The compiler changes a call to memset into a call to either 
_memset32 when compiled with /POINTER_SIZE=32, or memset64 when compiled 
with /POINTER_SIZE=64. 


You can override this default behavior by directly calling either the 32-bit or the 
64-bit form of the function. This accommodates applications using mixed-pointer 
sizes, regardless of the default pointer size specified with the /POINTER_SIZE 
qualifier. 


If the application is compiled without specifying the /POINTER_SIZE qualifier, 
neither the 32-bit specific nor the 64-bit specific function prototypes are defined. 
In this case, the compiler automatically calls the 32-bit interface for all interfaces 
having dual implementations. 


Table 1-6 shows the HP C RTL functions that have dual implementations to 
support 64-bit pointer size. When compiling with the /POINTER_SIZE qualifier, 
calls to the unmodified function names are changed to calls to the function 
interface that matches the pointer size specified on the qualifier. 


Table 1-6 Functions with Dual Implementations 


basename bsearch calloc catgets 
ctermid cuserid dirname fgetname 
fgets fgetws gcevt getcwd 
getname getpwent getpwnam getpwnam_r 
getpwuid getpwuid r gets index 
longname malloc mbsrtowcs memccpy 
memchr memcpy memmove memset 
mktemp mmap qsort readv 
realloc rindex streat strchr 
strcpy strdup strneat strncpy 
strpbrk strptime strrchr strsep 
strstr strtod strtok strtok r 
strtol strtoll strtog strtoul 
strtoull strtoug tmpnam wescat 


(continued on next page) 
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Table 1-6 (Cont.) Functions with Dual Implementations 


weschr wcescpy wesncat wesncpy 
wespbrk wesrchr wesrtombs wesstr 
westok westol westoul wcswcs 
wmemchr wmemcpy wmemmove wmemset 
writev glob globfree 


Table 1-7 shows the TCP/IP socket routines that have dual implementations to 
support 64-bit pointer size. 


Table 1-7 Socket Routines with Dual Implementations 


freeaddrinfo getaddrinfo 
recvmsg sendmsg 


1.10.4.4 Functions Requiring Explicit use of 64-Bit Structures 


Some functions require explicit use of 64-bit structures when compiling 
/POINTER_SIZE=LONG. This is necessary for functions that have recently 
had 64-bit support added to avoid unexpected runtime errors by inadvertently 
mixing 32-bit and 64-bit versions of structures. 


Consider the following functions: 


getaddrinfo getpwnam 
freeaddrinfo getpwnam r 
getpwuid getpwent 
sendmsg getpwent_r 
recvmsg 


These functions previously offered 32-bit support only, even when compiled 

with /POINTER_SIZE=LONG. In order to preserve the previous behavior of 
32-bit pointer support in those functions even when compiled with /POINTER_ 
SIZE=LONG, these seven functions do not follow the normal convention for 32-bit 
and 64-bit support as documented in the previous section. 


The following variants of these functions, and the corresponding structures they 
use, have been added to the C RTL to provide 64-bit support: 


Function Structure 
__getaddrinfo32 __addrinfo32 
__getaddrinfo64 __addrinfo64 
__freeaddrinfo32 __addrinfo32 
__freeaddrinfo64 __addrinfo64 
__recvmsg32 __msghdr32 
__recvmsg64 __msghdré4 
__sendmsg32 __msghdr32 
__sendmsg64 __msghdré4 
__32_getpwnam __passwd32 
__ 64 getpwnam __passwd64 


_getpwnam_r32 _ passwd32 
_getpwnam_ré4 _passwdé4 


__32_getpwuid __passwd32 
__64 getpwuid __passwd64 
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_getpwuid r32 _ passwd32 
_getpwuid ré4 — passwdé4 


__32_getpwent __passwd32 
__ 64 getpwent __passwd64 


When compiling the standard versions of these functions, the following behavior 
occurs: 


e With /POINTER_SIZE=32 specified, the compiler converts the call to the 
32-bit version of the function. For example, getaddrinfo is converted to 
__getaddrinfo32. 


e With /POINTER_SIZE=64 specified, the compiler converts the call to the 
64-bit version of the function. For example, getaddrinfo is converted to 
__getaddrinfoé4. 


e When the /POINTER_SIZE qualifier is not specified, neither the 32-bit-specific 
nor the 64-bit-specific function prototypes are defined. 


However, a similar conversion of the corresponding structures does not occur 

for these functions. This behavior is necessary because these structures existed 
before OpenVMS Version 7.3-2 as 32-bit versions only, even when compiled with 
/POINTER_SIZE=LONG. Implicitly changing the size of the structure could result 
in unexpected run-time errors. 


When compiling programs that use the standard version of these functions 

for 64-bit support, you must use the 64-bit-specific definition of the related 
structure. With /POINTER_SIZE=64 specified, compiling a program with the 
standard function name and standard structure definition will result in compiler 
PTRMISMATCH warning messages. 


For example, the following program uses the getaddrinfo and freeaddrinfo 
routines, along with the standard definition of the addrinfo structure. Compiling 
this program results in the warning messages shown: 


$ type test.c 
#include <netdb.h> 


int main () 


struct addrinfo *ai; 


getaddrinfo ("althea", 0, 0, &ai); 
freeaddrinfo (ai); 
return 0; 


} 


$ cc /pointer size=64 TEST.C 
getaddrinfo ("althea", 0, 0, &ai); 


$CC-W-PTRMISMATCH, In this statement, the referenced type of the pointer value 
"Gai" is "long pointer to struct addrinfo", which is not compatible with "long 
pointer to struct — addrinfo64". 

at line number 7 in file TEST.C;1 


freeaddrinfo (ai); 


$CC-W-PTRMISMATCH, In this statement, the referenced type of the pointer value 
"ai" is "struct addrinfo", which is not compatible with "struct _ addrinfoé4". 
at line number 8 in file TEST.C;1 

$ 
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When compiling for 64 bits, you need to use the 64-bit-specific version of the 
related structure. In the previous example, the declaration of the ai structure 
could be changed to the following: 


struct _addrinfo64 *ai; 


Or, to provide flexibility between 32-bit and 64-bit compilations, the ai structure 
could be declared as follows: 


#if INITIAL POINTER SIZE == 64 
struct _ addrinfo64 *ai; 
#else 
struct _addrinfo32 *ai; 
#endif 


1.10.4.5 Functions Restricted to 32-Bit Pointers 


A few functions in the HP C RTL do not support 64-bit pointers. If you try to 
pass a 64-bit pointer to one of these functions, the compiler generates a %CC- 
W-MAYLOSEDATA warning. Applications compiled with /POINTER_SIZE=64 
might need to be modified to avoid passing 64-bit pointers to these functions. 


Table 1-8 shows the functions restricted to using 32-bit pointers. The HP C RTL 
offers no 64-bit support for these functions. You must ensure that only 32-bit 
pointers are used with these functions. 


Table 1-8 Functions Restricted to 32-Bit Pointers 


atexit frexp ioctl setbuf 
execv getopt modft setstate 
execve iconv putenv setvbuf 
execvp initstate 


Table 1-9 shows functions that make callbacks to user-supplied functions as part 
of processing that function call. The callback procedures are not passed 64-bit 
pointers. 


Table 1-9 Callbacks that Pass Only 32-Bit Pointers 


deccS$from_vms deccS$to_vms 
ftw tputs 


1.10.5 Reading Header Files 


This section introduces the pointer-size manipulations used in the HP C RTL 
header files. Use the following examples to become more proficient in reading 
these header files and to help modify your own header files. 
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Examples 


1. 
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#i£ INITIAL POINTER SIZE 1 


if (_ VMS VER < 70000000) || !defined ALPHA 2 
error " Pointer size usage not permitted before OpenVMS Alpha V7.0" 
# endif 
pragma pointer size save 3 
pragma __ pointer size 32 4 
endif 
#1 INITIAL POINTER SIZE 5 
pragma __ pointer size 64 
endif 
#i£ INITIAL POINTER SIZE 6 
pragma pointer size restore 


endif 


All HP C compilers that support the /POINTER_SIZE qualifier predefine 
the _ INITIAL POINTER SIZE macro. The HP C RTL header files take 
advantage of the ANSI rule that if a macro is not defined, it has an implicit 
value of 0. 


The macro is defined as 32 or 64 when the /POINTER_SIZE qualifier is used. 
It is defined as 0 if the qualifier is not used. The statement at 1 can be 
read as "if the user has specified either /POINTER_SIZE=32 or /POINTER_ 
SIZE=64 on the command line". 


The C compiler is supported on many OpenVMS versions. The lines at 2 
generate an error message if the target of the compilation is one that does not 
support 64-bit pointers. 


A header file cannot assume anything about the actual pointer-size context 
in effect at the time the header file is included. Furthermore, the HP C 
compiler offers only the __INITIAL_POINTER_SIZE macro and a mechanism 
to change the pointer size, but not a way to determine the current pointer 
size. 


All header files that have a dependency on pointer sizes are responsible for 
saving 3 , initializing 4 , altering 5 , and restoring 6 the pointer-size context. 


#ifndef CHAR PTR32 1 
# define CHAR PTR32 1 

typedef char * char _ptr32; 

typedef const char * __ const_char ptr32; 
#endif 


#if INITIAL POINTER SIZE 
# pragma pointer size 64 
#endif 


#ifndef CHAR PTR64 2 
# define CHAR PTR64 1 
typedef char * __ char ptré4; 
typedef const char * __ const_char ptré4; 


#endif 


Some function prototypes need to refer to a 32-bit pointer when in a 64-bit 
pointer-size context. Other function prototypes need to refer to a 64-bit 
pointer when in a 32-bit pointer-size context. 


HP C binds the pointer size used in a typedef at the time the typedef 
is made. Assuming this header file is compiled with no /POINTER_SIZE 
qualifier or with /POINTER_SIZE=SHORT, the typedef declaration of 
__ char ptr321 is made in a 32-bit context. The typedef declaration of 
__char ptr6é4 2 is made in a 64-bit context. 


#if INITIAL POINTER SIZE 

# if (__ VMS VER < 70000000) || !defined _ ALPHA 

# error " Pointer size usage not permitted before OpenVMS Alpha V7.0" 
# = ~=©endif 

# pragma pointer size ___save 

# pragma pointer size 32 

ends 


#if | INITIAL POINTER SIZE 2 


# pragma pointer size 64 
#endif 
3 


int abs (int _j); 4 


__ char ptr32 strerror (int _errnum); 5 


Before declaring function prototypes that support 64-bit pointers, the pointer 
context is changed 2 from 32-bit pointers to 64-bit pointers. 


Functions restricted to 32-bit pointers are placed in the 32-bit pointer context 
section 1 of the header file. All other functions are placed in the 64-bit 
context section 3 of the header file. 
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Functions that have no pointer-size impact (4 and 5 ) are located in the 
64-bit section. Functions that have no pointer-size impact except for a 32-bit 
address return value 5 are also in the 64-bit section, and use the 32-bit 
specific typedefs previously discussed. 


#i£ | INITIAL POINTER SIZE 
pragma __ pointer _size 64 
endif 


#i£ INITIAL POINTER SIZE == 32 1 


# pragma pointer size 32 
endif 
char *strceat (char * sl, ___comst_char ptr6é4 _—s2); 2 


#i£ INITIAL POINTER SIZE 


# pragma pointer size 32 
char * strcat32 (char * sl, __const_char ptré4 _s2); 3 
# pragma pointer size 64 


char * strcat64 (char * sl, const char * 82); 4 


Hendif 


This example shows declarations of functions that have both a 32-bit and 
64-bit implementation. These declarations are located in the 64-bit section of 
the header file. 


The normal interface to the function 2 is declared using the pointer size 
specified on the /POINTER_SIZE qualifier. Because the header file is in 64- 
bit pointer context and because of the statements at 1 , the declaration at 2 
is made using the same pointer-size context as the /POINTER_SIZE qualifier. 


The 32-bit specific interface 3 and the 64-bit specific interface 4 are declared 
in 32-bit and 64-bit pointer-size context, respectively. 
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Understanding Input and Output 


There are three types of input and output (I/O) in the HP C Run-Time Library 
(RTL): UNIX, Standard, and Terminal. Table 2—1 lists all the I/O functions and 
macros found in the HP C RTL. For more detailed information on each function 
and macro, see the Reference Section. 


Table 2-1 1/O Functions and Macros 


Function or Macro Description 


UNIX I/O—Opening and Closing Files 


close Closes the file associated with a file descriptor. 
creat Creates a new file. 
dup, dup2 Allocates a new descriptor that refers to a file specified by a 


file descriptor returned by open, creat, or pipe. 
open Opens a file and positions it at its beginning. 


UNIX I/O—Reading from Files 


read Reads bytes from a file and places them in a buffer. 


UNIX I/O—Writing to Files 


write Writes a specified number of bytes from a buffer to a file. 


UNIX I/O—Maneuvering in Files 


lseek Positions a stream file to an arbitrary byte position and returns 
the new position as an int. 


(continued on next page) 
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Table 2-1 (Cont.) I/O Functions and Macros 


Function or Macro 


Description 


UNIX I/O—Additional X/Open I/O Functions and Macros 


fstat, stat 


flockfile, 
ftrylockfile, 
funlockfile 


fsynec 
getname 
isapipe 


isatty 


lwait 
ttyname 


Accesses information about the file descriptor or the file 
specification. 


File-pointer-locking functions. 


Writes to disk any buffered information for the specified file. 
Returns the file specification associated with a file descriptor. 


Returns 1 if the file descriptor is associated with a pipe and 0 
if it is not. 

Returns 1 if the specified file descriptor is associated with a 
terminal and 0 if it is not. 

Waits for completion of pending asynchronous I/O. 


Returns a pointer to the null-terminated name of the terminal 
device associated with file descriptor 0, the default input 
device. 


Standard Il/O—Opening and Closing Files 


fclose 


fdopen 


fopen 
freopen 


Closes a function by flushing any buffers associated with the 
file control block, and freeing the file control block and buffers 
previously associated with the file pointer. 


Associates a file pointer with a file descriptor returned by an 
open, creat, dup, dup2, or pipe function. 


Opens a file by returning the address of a FILE structure. 


Substitutes the file, named by a file specification, for the open 
file addressed by a file pointer. 


Standard I/O—Reading from Files 


fgetc, getc, fgetwc, 
getw, getwc 


fgets, fgetws 


fread 


fscanf, fwscanf, 
vfscanf, vfwscanf 


sscanf, swscanf, 
vsscanf, vswscanf 


ungetc, ungetwc 


2-2 Understanding Input and Output 


Returns characters from a specified file. 


Reads a line from a specified file and stores the string in an 
argument. 


Reads a specified number of items from a file. 


Performs formatted input from a specified file. 
Performs formatted input from a character string in memory. 
Pushes back a character into the input stream and leaves the 


stream positioned before the character. 


(continued on next page) 


Table 2-1 (Cont.) I/O Functions and Macros 


Description 


Function or Macro 


Standard I/O—Writing to Files 


fprintf, fwprintf, Performs formatted output to a specified file. 


vfprintf, vfwprintf 


fputc, putc, putw, Writes characters to a specified file. 


putwce, fputwc 
fputs, fputws 


fwrite 


sprintf, swprintf, 
vsprintf, vswprintf 


Writes a character string to a file without copying the string’s 
null terminator. 


Writes a specified number of items to a file. 


Performs formatted output to a string in memory. 


Standard I/O—Maneuvering in Files 


fflush 
fgetpos 


fsetpos 


fseek, fseeko 
ftell, ftello 


rewind 


Sends any buffered information for the specified file to RMS. 


Stores the current value of the file position indicator for the 
stream. 


Sets the file position indicator for the stream according to the 
value of the object pointed to. 


Positions the file to the specified byte offset in the file. 
Returns the current byte offset to the specified stream file. 
Sets the file to its beginning. 


Standard I/O—Additional Standard I/O Functions and Macros 


access 
clearerr 
feof 
ferror 


fgetname 
fileno 


ftruncate 
fwait 

fwide 

mktemp 

remove, delete 
rename 

setbuf, setvbuf 
tmpfile 

tmpnam 


Checks a file to see whether a specified access mode is allowed. 
Resets the error and end-of-file indications for a file. 
Tests a file to see if the end-of-file has been reached. 


Returns a nonzero integer if an error has occurred while 
reading or writing a file. 


Returns the file specification associated with a file pointer. 


Returns an integer file descriptor that identifies the specified 
file. 


Truncates a file at the specified position. 

Waits for completion of pending asynchcronous I/O. 

Sets the orientation a stream. 

Creates a unique file name from a template. 

Deletes a file. 

Gives a new name to an existing file. 

Associates a buffer with an input or output file. 

Creates a temporary file that is opened for update. 

Creates a character string that can be used in place of the 


file-name argument in other function calls. 


(continued on next page) 
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Table 2-1 (Cont.) I/O Functions and Macros 


Function or Macro Description 


Terminal |/O—Reading from Files 


getchar, getwchar Reads a single character from the standard input (stdin). 
gets Reads a line from the standard input (stdin). 
scanf, wscanf, Performs formatted input from the standard input. 


vscanf, vwscanf 


Terminal l/O—Writing to Files 


printf, wprintf, Performs formatted output to the standard output (stdout). 
vprintf, vwprintf 


putchar, putwchar Writes a single character to the standard output and returns 
the character. 


puts Writes a character string to the standard output followed by a 
new-line character. 


2.1 Using RMS from RTL Routines 


When you create a file using the HP C RTL I/O functions and macros, you can 
supply values for many RMS file attributes, including: 


e Allocation quantity 

e Block size 

e Default file extension 

e Default file name 

e File access context options 
e File-processing options 

e File-sharing options 

e = Multiblock count 

e Multibuffer count 

e Maximum record size 

e Record attributes 

e Record format 

e Record-processing options 


See the description of the creat function in the Reference Section for information 
on these values. 


Other functions that allow you to set these values include open, fopen, and 
freopen. 


For more information about RMS, see the HP C User’s Guide for OpenVMS 
Systems. 
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2.2 UNIX I/O and Standard I/O 


UNIX I/O functions are UNIX system services, now standardized by ISO POSIX-1 
(the ISO Portable Operating System Interface). 


UNIX I/O functions use file descriptors to access files. A file descriptor is an 
integer that identifies the file. A file descriptor is declared in the following way, 
where file_desc is the name of the file descriptor: 


int file desc; 


UNIX I/O functions, such as creat, associate the file descriptor with a file. 
Consider the following example: 


file descl = creat("INFILE.DAT", 0, "rat=cr", "rfm=var") ; 


This statement creates the file, INFILE.DAT, with file access mode 0, carriage- 
return control, variable-length records, and it associates the variable file descl 
with the file. When the file is accessed for other operations, such as reading or 
writing, the file descriptor is used to refer to the file. For example: 


write(file descl, buffer, sizeof (buffer) ) ; 
This statement writes the contents of the buffer to INFILE.DAT. 


There may be circumstances when you should use UNIX I/O functions and macros 
instead of the Standard I/O functions and macros. For a detailed discussion of 
both forms of I/O and how they manipulate the RMS file formats, see Chapter 1. 


Standard I/O functions are specified by the ANSI C Standard. 


Standard I/O functions add buffering to the features of UNIX I/O and use file 
pointers to access files. A file pointer is an object of type FILE *, which is a 
typedef defined in the <stdio.h> header file as follows: 


typedef struct _iobuf *FILE; 

The _iobuf identifier is also defined in <stdio.h>. 
To declare a file pointer, use the following: 

FILE *file ptr; 


Use the Standard I/O fopen function to create or open an existing file. For 
example: 


#include <stdio.h> 


main () 


FILE *outfile; 
outfile = fopen("DISKFILE.DAT", "w+"); 


} 
Here, the file DISKFILE.DAT is opened for write-update access. 


The HP C RTL provides the following functions for converting between file 
descriptors and file pointers: 


e fileno—returns the file descriptor associated with the specified file pointer. 


e fdopen—associates a file pointer with a file descriptor returned by an open, 
creat, dup, dup2, or pipe function. 
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2.3 Wide-Character Versus Byte I/O Functions 


The wide-character I/O functions provide operations similar to most of the byte 
I/O functions, except that the fundamental units internal to the wide-character 
functions are wide characters. 


However, the external representation (in files) is a sequence of multibyte 
characters, not wide characters. For the wide-character formatted input and 
output functions: 


e The wide-character formatted input functions (such as fwscanf) always read 
a sequence of multibyte characters from files, regardless of the specified 
directive and, before any further processing, convert this sequence to a 
sequence of wide characters. 


e The wide-character formatted output functions (such as fwprintf) write wide 
characters to output files by first converting wide-character argument types 
to a sequence of multibyte characters, then calling the underlying operating 
system output primitives. 


Byte I/O functions cannot handle state-dependent encodings. Wide-character I/O 
functions can. They accomplish this by associating each wide-character stream 
with a conversion-state object of type mbstate t. 


The wide-character I/O functions are: 


fgetwe fputwe fwscant fwprintf ungetwc 
fgetws fputws wscanf wprintf 

getwe putwe vfwprintf 

getwchar putwchar vwprintf 


The byte I/O functions are: 


fgetc fputc fscanf fprintf ungetc 
fgets fputs scant printf fread 
getc putc vfprinf fwrite 
gets puts vprintf 

getchar putchar 


The wide-character input functions read multibyte characters from the stream 
and convert them to wide characters as if they were read by successive calls to 
the fgetwc function. Each conversion occurs as if a call were made to the mbrtowc 
function with the conversion state described by the stream’s own mbstate t 
object. 


The wide-character output functions convert wide characters to multibyte 
characters and write them to the stream as if they were written by successive 
calls to the fputwc function. Each conversion occurs as if a call were made to the 
wcrtomb function, with the conversion state described by the I/O stream’s own 
mbstate t object. 


If a wide-character I/O function encounters an invalid multibyte character, the 
function sets errno to the value EILSEQ. 
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2.4 Conversion Specifications 


Several of the Standard I/O functions (including the Terminal I/O functions) use 
conversion specifications to specify data formats for I/O. These functions are the 
formatted-input and formatted-output functions. Consider the following example: 


int x = 5.0; 
FILE *outfile; 


fprintf(outfile, "The answer is %d.\n", x); 


The decimal value of the variable x replaces the conversion specification %d in the 
string to be written to the file associated with the identifier outfile. 


Each conversion specification begins with a percent sign (%) and ends with a 
conversion specifier, which is a character that specifies the type of conversion to 
be performed. Optional characters can appear between the percent sign and the 
conversion specifier. 


For the wide-character formatted I/O functions, the conversion specification is a 
string of wide characters. For the byte I/O equivalent functions, it is a string of 
bytes. 


Sections 2.4.1 and 2.4.2 describe these optional characters and conversion 
specifiers. 


2.4.1 Converting Input Information 


The format specification string for the input of information can include three 
kinds of items: 


e White-space characters (spaces, tabs, and new-line characters), which match 
optional white-space characters in the input field. 


e Ordinary characters (not %), which must match the next nonwhite-space 
character in the input. 


e Conversion specifications, which govern the conversion of the characters in 
an input field and their assignment to an object indicated by a corresponding 
input pointer. 


Each input pointer is an address expression indicating an object whose 

type matches that of a corresponding conversion specification. Conversion 
specifications form part of the format string. The indicated object is the target 
that receives the input value. There must be as many input pointers as there are 
conversion specifications, and the addressed objects must match the types of the 
conversion specifications. 


A conversion specification consists of the following characters, in the order listed: 


e A percent character (%) or the sequence %n$ (where n is an integer), 


The sequence %n$ denotes that the conversion is applied to the nth input 
pointer listed, where n is a decimal integer between [1, NL_LARGMAX] 

(see the <limits.h> header file). For example, a conversion specification 
beginning with %5$ means that the conversion will be applied to the fifth 
input pointer listed after the format specification. The sequence %$ is invalid. 
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If the conversion specification does not begin with the sequence %n$, the 
conversion specification is matched to its input pointer in left-to-right order. 
You should only use one type of conversion specification (% or %n$) in a 
format specification. 


e One or more optional characters (see Table 2-2). 


e A conversion 


specifier (see Table 2-3). 


Table 2-2 shows the characters you can use between the percent sign (%) (or the 
sequence %n$), and the conversion specifier. These characters are optional but, if 
specified, must occur in the order shown in Table 2-2. 


Table 2-2 Optional Characters Between % (or %n$) and the Input Conversion 


Specifier 
Character Meaning 
= An assignment-suppressing character. 
field width A nonzero decimal integer that specifies the maximum field width. 


h, 1, or L (or Il) 


For the wide-character input functions, the field width is measured in 
wide characters. 


For the byte input functions, the field width is measured in bytes, 
unless the directive is one of the following: 


slc, sls, %C, %S, %[ 


In these cases, the field width is measured in multibyte character 
units. 


Precede a conversion specifier of d, i, or n with an h if the 
corresponding argument is a pointer to short int rather than a 
pointer to int; with an | (lowercase ell) if it is a pointer to long int; 
or, for OpenVMS Alpha systems only, with an L or Il (two lowercase 
ells) ifit is a pointer to __inté4. 


Precede a conversion specifier of 0, u, or x with an h if the 
corresponding argument is a pointer to unsigned short int rather 
than a pointer to unsigned int; with an 1 if it is a pointer to 
unsigned long int; or, for OpenVMS Alpha systems only, with an 
Lor llifit is a pointer tounsigned _inté4. 


Precede a conversion specifier of c, s, or [ with an 1 (lowercase ell) if the 
corresponding argument is a pointer to a wchar t. 


Finally, precede a conversion specifier of e, f, or g with an 1 (lowercase 
ell) if the corresponding argument is a pointer to double rather than a 
pointer to float, or with an Lif it is a pointer to long double. 


If an h, 1, L, or ll appears with any other conversion specifier, then the 
behavior is undefined. 


Table 2-3 describes the conversion specifiers for formatted input. 
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Table 2-3 Conversion Specifiers for Formatted Input 


Specifier 


Input Type’ 


Description 


d 


Byte 


Wide-character 


Expects a decimal integer in the input whose format 
is the same as expected for the subject sequence of 
the strtol function with the value 10 for the base 
argument. The corresponding argument must be a 
pointer to int. 


Expects an integer whose type is determined by the 
leading input characters. A leading 0 is equated to octal, 
a leading OX or Ox is equated to hexadecimal, and all 
other forms are equated to decimal. The corresponding 
argument must be a pointer to int. 


Expects an octal integer in the input (with or without 
a leading 0). The corresponding argument must be a 
pointer to int. 


Expects a decimal integer in the input whose format 
is the same as expected for the subject sequence of 
the strtoul function with the value 10 for the base 
argument. 


Expects a hexadecimal integer in the input (with or 
without a leading 0x). The corresponding argument 
must be a pointer to unsigned int. 


Expects a single byte in the input. The corresponding 
argument must be a pointer to char. 


If a field width precedes the c conversion specifier, then 
the number of characters specified by the field width is 
read. In this case, the corresponding argument must be 
a pointer to an array of char. 


If the optional character 1 (lowercase ell) precedes 

this conversion specifier, then the specifier expects a 
multibyte character in the input which is converted into 
a wide-character code. 


The corresponding argument must be a pointer to type 
wchar t. Ifa field width also precedes the c conversion 
specifier, then the number of characters specified by 
the field width is read. In this case, the corresponding 
argument must be a pointer to an array of wchar _t. 


Expects a sequence of the number of characters specified 
in the optional field width; this is 1 if not specified. 


If no | (lowercase ell) precedes the c specifier, then the 
corresponding argument must be a pointer to an array of 
char. 


If an | (lowercase ell) precedes the c specifier, then the 
corresponding argument must be a pointer to an array of 
wchar t. 


lBither byte or wide-character. Where neither is shown for a given specifier, the specifier description 
applies to both. 


(continued on next page) 
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Table 2-3 (Cont.) Conversion Specifiers for Formatted Input 


Specifier Input Type’ 


Description 


C Byte 


Wide-character 


s Byte 


Wide-character 


S Byte 


Wide-character 


The specifier expects a multibyte character in the input, 
which is converted into a wide-character code. The 
corresponding argument must be a pointer to type 
wchar t. 


If a field width also precedes the C conversion specifier, 
then the number of characters specified by the field 
width is read. In this case, the corresponding argument 
must be a pointer to an array of wchar t. 


Expects a sequence of the number of characters specified 
in the optional field width; this is 1 if not specified. The 
corresponding argument must be a pointer to an array of 
wchar t. 


Expects a sequences of bytes in the input. The 
corresponding argument must be a pointer to an 

array of characters that is large enough to contain 

the sequence and a terminating null character (\ 0) that 
is automatically added. The input field is terminated by 
a space, tab, or new-line character. 


If the optional character | (ell) precedes this conversion 
specifier, then the specifier expects a sequence of 
multibyte characters in the input, which are converted 
to wide-character codes. The corresponding argument 
must be a pointer to an array of wide characters (type 
wchar_t) that is large enough to contain the sequence 
plus the terminating null wide-character code that is 
automatically added. The input field is terminated by a 
space, tab, or new-line character. 


Expects (conceptually) a sequence of nonwhite-space 
characters in the input. 


If no 1 (lowercase ell) precedes the s specifier, then the 
corresponding argument must be a pointer to an array 
of char large enough to contain the sequence plus the 
terminating null byte that is automatically added. 


If an | (lowercase ell) precedes the s specifier, then the 
corresponding argument must be a pointer to an array of 
wchar t large enough to contain the sequence plus the 
terminating null wide character that is automatically 
added. 


The specifier expects a sequence of multibyte characters 
in the input, which are converted to wide-character 
codes. The corresponding argument must be a pointer 
to an array of wide characters (type wchar_t) that is 
large enough to contain the sequence plus a terminating 
null wide-character code that is added automatically. 
The input field is terminated by a space, tab, or new-line 
character. 


Expects a sequence of nonwhite-space characters in the 
input. The corresponding argument must be a pointer 
to an array of wchar t large enough to contain the 
sequence plus the terminating null wide character that 
is automatically added. 


lRither byte or wide-character. Where neither is shown for a given specifier, the specifier description 


applies to both. 
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(continued on next page) 


Table 2-3 (Cont.) Conversion Specifiers for Formatted Input 


Specifier Input Type’ 


Description 


e, fig 


Byte 


Expects a floating-point number in the input. The 
corresponding argument must be a pointer to float. 
The input format for floating-point numbers is: 

[+]nnn [radix] [ddd][{E | e}[+]nn]. The n’s and d’s are 
decimal digits (as many as indicated by the field width 
minus the signs and the letter E). The radix character is 
defined in the current locale. 


Expects a nonempty sequence of characters that is not 
delimited by a white-space character. The brackets 
enclose a set of characters (the scanset) expected 

in the input sequence. Any character in the input 
sequence that does not match a character in the scanset 
terminates the character sequence. 


All characters between the brackets comprise the 
scanset, unless the first character after the left bracket 
is a circumflex (‘). In this case, the scanset contains 
all characters other than those that appear between 
the circumflex and the right bracket. Any character 
that does appear between the circumflex and the right 
bracket will terminate the input character sequence. 


If the conversion specifier begins with [] or [], then the 
right bracket character is in the scanset and the next 
right bracket character is the matching right bracket 
that ends the specification; otherwise, the first right 
bracket character ends the specification. 


If an | (lowercase ell) does not precede the [ specifier, 
then the characters in the scanset must be single- 
byte characters only. In this case, the corresponding 
argument must be a pointer to an array of char large 
enough to accept the sequence and the terminating null 
byte that is automatically added. 


If an | (lowercase ell) does precede the [ specifier, then 
the characters in the input sequence are considered 

to be multibyte characters, which are then converted 

to a wide-character sequence for further processing. 

If character ranges are specified in the scanset, then 
the processing is done according to the LC_COLLATE 
category of the current program’s locale. In this case, the 
corresponding argument must be a pointer to an array 
of wchar_t large enough to accept the sequence and the 
terminating null wide character that is automatically 
added. 


lBither byte or wide-character. Where neither is shown for a given specifier, the specifier description 


applies to both. 


(continued on next page) 
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Table 2-3 (Cont.) Conversion Specifiers for Formatted Input 


Specifier Input Type’ Description 


Wide-character If no | (lowercase ell) precedes the [ conversion specifier, 
then processing is the same as described for the 
byte-input type of the %l[ specifier, except that the 
corresponding argument must be an array of char 
large enough to accept the multibyte sequence plus the 
terminating null byte that is automatically added. 


If an 1 (lowercase ell) precedes the [ conversion specifier, 
then processing is the same as in the preceding 
paragraph except that the corresponding argument 
must be an array of wchar_t large enough to accept the 
wide-character sequence plus the terminating null wide 
character that is automatically added. 


p Requires an argument that is a pointer to void. The 
input value is interpreted as a hexadecimal value. 


n No input is consumed. The corresponding argument 
is a pointer to an integer. The integer is assigned the 
number of characters read from the input stream so far 
by this call to the formatted input function. Execution of 
a %n directive does not increment the assignment count 
returned when the formatted input function completes 
execution. 


% Matches a single percent symbol. No conversion or 
assignment takes place. The complete conversion 
specification would be %%. 


lRither byte or wide-character. Where neither is shown for a given specifier, the specifier description 
applies to both. 


Remarks 


e You can change the delimiters of the input field with the bracket (| ]) 
conversion specification. Otherwise, an input field is defined as a string 
of nonwhite-space characters. It extends either to the next white-space 
character or until the field width, if specified, is exhausted. The function 
reads across line and record boundaries, since the new-line character is a 
white-space character. 


e Acall to one of the input conversion functions resumes searching immediately 
after the last character processed by a previous call. 


e If the assignment-suppression character (*) appears in the format 
specification, no assignment is made. The corresponding input field is 
interpreted and then skipped. 


e The arguments must be pointers or other address-valued expressions, since 
HP C permits only calls by value. To read a number in decimal format and 
assign its value to n, you must use the following form: 


scanf("Sd", &n) 
You cannot use the following form: 
scanf("Sd", n) 


e White space in a format specification matches optional white space in the 
input field. Consider the following format specification: 


field = %x 
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This format specification matches the following forms: 


field = 5218 
field=5218 

field= 5218 
field =5218 


These forms do not match the following example: 


fiel d=5218 


2.4.2 Converting Output Information 


The format specification string for the output of information can contain: 


Ordinary characters, which are copied to the output. 


Conversion specifications, each of which causes the conversion of a 
corresponding output source to a character string in a particular format 
Conversion specifications are matched to output sources in left-to-right order. 


A conversion specification consists of the following, in the order listed: 


A percent character (%) or the sequence %n$. 


The sequence %n$ denotes that the conversion is applied to the nth output 
source listed, where n is a decimal integer between [1, NL_ARGMAX] (see the 
<limits.h> header file). For example, a conversion specification beginning 
with %5$ means that the conversion will be applied to the fifth output source 
listed after the format specification. 


If the conversion specification does not begin with the sequence %n$, the 
conversion specification is matched to its output source in left-to-right order. 
You should only use one type of conversion specification (% or %n$) in a 
format specification. 


One or more optional characters (see Table 2-4). 


A conversion specifier (see Table 2-5) concludes the conversion specification. 


For examples of conversion specifications, see the sample programs in Section 2.6. 


Table 2-4 shows the characters you can use between the percent sign (% ) (or the 
sequence %n$) and the conversion specifier. These characters are optional, but if 
specified, they must occur in the order shown in Table 2-4. 
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Table 2-4 Optional Characters Between % (or %n$) and the Output Conversion 


Specifier 


Character Meaning 


flags You can use the following flag characters, alone or in any combined order, 
to modify the conversion specification: 


’ (single 
quote) 


— (hyphen) 


space 
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Requests that a numeric conversion is formatted with 
the thousands separator character. Only the numbers 
to the left of the radix character are formatted with the 
separator character. The character used as a separator 
and the positioning of the separators are defined in the 
program’s current locale. 


Left-justifies the converted output source in its field. 


Requests that an explicit sign be present on a signed 
conversion. If this flag is not specified, the result of a 
signed conversion begins with a sign only when a negative 
value is converted. 


Prefixes a space to the result of a signed conversion, if 
the first character of the conversion is not a sign, or if the 
conversion results in no characters. If you specify both the 
space and the + flag, the space flag is ignored. 


Requests an alternate conversion format. Depending on 
the conversion specified, different actions will occur. 


For the o (octal) conversion, the precision is increased to 
force the first digit to be a zero. 


For the x (or X) conversion, a nonzero result is prefixed 
with Ox (or OX). 


For e, E, f, g, and G conversions, the result contains a 
decimal point even at the end of an integer value. 


For g and G conversions, trailing zeros are not trimmed. 
For other conversions, the effect of # is undefined. 


Uses zeros rather than spaces to pad the field width for d, 
i, 0, u, x, X, e, E, f, g, and G conversions. If both the 0 and 
the — flags are specified, then the 0 flag is ignored. For d, 
i, 0, u, x, and X conversions, if a precision is specified, the 
0 flag is ignored. For other conversions, the behavior of 
the 0 flag is undefined. 
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Table 2-4 (Cont.) Optional Characters Between % (or %n$) and the Output 


Conversion Specifier 


Character 


Meaning 


field width 


. (period) 


precision 


The minimum field width can be designated by a decimal integer 
constant, or by an output source. To specify an output source, use an 
asterisk (*) or the sequence “n$, where n refers to the nth output source 
listed after the format specification. 


The minimum field width is considered after the conversion is done 
according to all the other components of the format directive. This 
component affects the padding of the conversion result as follows: 


If the result of the conversion is wider than the minimum field, write it 
out. 


If the result of the conversion is narrower than the minimum width, pad 
it to make up the field width. Pad with spaces by default. Pad with zeros 
if the 0 flag is specified; this does not mean that the width is an octal 
number. Padding is on the left by default, and on the right if a minus 
sign is specified. 


For the wide-character output functions, the field width is measured in 
wide characters; for the byte output functions, it is measured in bytes. 


Separates the field width from the precision. 


The precision defines any of the following: 


e Minimum number of digits to appear for d, i, 0, u, x, and X 
conversions 


e Number of digits to appear after the decimal-point character for e, 
E, and f conversions 


e Maximum number of significant digits for g and G conversions 


e Maximum number of characters to be written from a string in an s 
or S conversion 


If a precision appears with any other conversion specifier, the behavior is 
undefined. 


Precision can be designated by a decimal integer constant, or by an 
output source. To specify an output source, use an asterisk (*) or the 
sequence *n$, where n refers to the nth output source listed after the 
format specification. 


If only the period is specified, the precision is taken as 0. 


(continued on next page) 
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Table 2-4 (Cont.) Optional Characters Between % (or %n$) and the Output 
Conversion Specifier 


Character Meaning 


h,1l, or L(orll) Anh specifies that a following d, i, 0, u, x, or X conversion specifier 
applies to a Short int or unsigned short int argument; an h can also 
specify that a following n conversion specifier applies to a pointer to a 
short int argument. 


An | (lowercase ell) specifies that a following d, i, 0, u, x, or X conversion 
specifier applies to a long int or unsigned long int argument; an 

1 can also specify that a following n conversion specifier applies to a 
pointer to a long int argument. 


On OpenVMS Alpha and I64 systems, an L or Il (two lowercase ells) 
specifies that a following d, i, 0, u, x, or X conversion specifier applies to 
an__inté4orunsigned _int64 argument. (Alpha, 164) 

An L specifies that a following e, E, f, g, or G conversion specifier applies 
to a long double argument. 

An | specifies that a following c or s conversion specifier applies to a 
wchar_t argument. 

If an h, 1, or L appears with any other conversion specifier, the behavior 
is undefined. 

On OpenVMS VAX and OpenVMS Alpha systems, HP C int values are 
equivalent to long values. 


Table 2-5 describes the conversion specifiers for formatted output. 


Table 2-5 Conversion Specifiers for Formatted Output 


Specifier Output Type’ Description 

d,i Converts an int argument to signed decimal format. 

) Converts an unsigned int argument to unsigned octal 
format. 

u Converts an unsigned int argument to unsigned decimal 


format (giving a number in the range 0 to 4,294,967,295). 


x, X Converts an unsigned int argument to unsigned 
hexadecimal format (with or without a leading Ox). The 
letters abcdef are used for x conversion, and the letters 
ABCDEF are used for X conversion. 


lRither byte or wide-character. Where neither is shown for a given specifier, the specifier description 
applies to both. 
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Table 2—5 (Cont.) Conversion Specifiers for Formatted Output 


Specifier Output Type’ 


Description 


f 


e, E 


g,G 


c Byte 


Converts a float or double argument to the format 
[-[mmm.nnnnnn. The number of n’s is equal to the precision 
specification as follows: 


e If no precision is specified, the default is 6. 


e Ifthe precision is 0 and the # flag is specified, the decimal 
point appears but no n’s appear. 


e Ifthe precision is 0 and the # flag is not specified, the 
decimal point also does not appear. 


e Ifa decimal point appears, at least one digit appears 
before it. 


The value is rounded to the appropriate number of digits. 


Converts a float or double argument to the format 
[-Jm.nnnnnnE+xx. The number of n’s is specified by the 
precision. If no precision is specified, the default is 6. If the 
precision is explicitly 0 and the # flag is specified, the decimal 
point appears but no n’s appear. If the precision is explicitly 
0 and the # flag is not specified, the decimal point also does 
not appear. An’e’ is printed for e conversion; an ’E’ is printed 
for E conversion. The exponent always contains at least two 
digits. If the value is 0, the exponent is 0. 


Converts a float or double argument to format f or e (or 

E if the G conversion specifier is used), with the precision 
specifying the number of significant digits. If the precision 
is 0, it is taken as 1. The format used depends on the value 
of the argument: format e (or E) is used only if the exponent 
resulting from such a conversion is less than —4, or is greater 
than or equal to the precision; otherwise, format f is used. 
Trailing zeros are suppressed in the fractional portion of the 
result. A decimal point appears only if it is followed by a 
digit. 

Converts an int argument to an unsigned char, and writes 
the resulting byte. 


If the optional character | (lowercase ell) precedes this 
conversion specifier, then the specifier converts a wchar_t 
argument to an array of bytes representing the character, and 
writes the resulting character. If the field width is specified 
and the resulting character occupies fewer bytes than the field 
width, then it will be padded to the given width with space 
characters. If the precision is specified, then the behavior is 
undefined. 


Hither byte or wide-character. Where neither is shown for a given specifier, the specifier description 


applies to both. 
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Table 2-5 (Cont.) Conversion Specifiers for Formatted Output 


Specifier Output Type’ 


Description 


Wide-character 


Cc Byte 


Wide-character 


s Byte 


If an | (lowercase ell) does not precede the c specifier, then the 
int argument is converted to a wide character as if by calling 
btowc, and the resulting character is written. 


If an | (lowercase ell) precedes the c specifier, then the 
specifier converts a wchar_t argument to an array of 
bytes representing the character, and writes the resulting 
character. If the field width is specified and the resulting 
character occupies fewer characters than the field width, it 
will be padded to the given width with space characters. If 
the precision is specified, the behavior is undefined. 


Converts a wchar_t argument to an array of bytes 
representing the character, and writes the resulting character. 
If the field width is specified and the resulting character 
occupies fewer bytes than the field width, then it will be 
padded to the given width with space characters. If the 
precision is specified, then the behavior is undefined. 


Converts a wchar_t argument to an array of bytes 
representing the character, and writes the resulting character. 
If the field width is specified and the resulting character 
occupies fewer wide characters than the field width, then it 
will be padded to the given width with space characters. If 
the precision is specified, then the behavior is undefined. 


Requires an argument that is a pointer to an array of 
characters of type char. The argument is used to write 
characters until a null character is encountered or until the 
number of characters indicated by the precision specification 
is exhausted. If the precision specification is 0 or omitted, 
then all characters up to a null are output. 


If the optional character | (lowercase ell) precedes this 
conversion specifier, then the specifier converts an array of 
wide-character codes to multibyte characters, and writes the 
multibyte characters. Requires an argument that is a pointer 
to an array of wide characters of type wchar_t. Characters 
are written until a null wide character is encountered or until 
the number of bytes indicated by the precision specification 
is exhausted. If the precision specification is omitted or is 
greater than the size of the array of converted bytes, then the 
array of wide characters must be terminated by a null wide 
character. 


lRither byte or wide-character. Where neither is shown for a given specifier, the specifier description 


applies to both. 
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(continued on next page) 


Table 2-5 (Cont.) Conversion Specifiers for Formatted Output 


Specifier Output Type’ 


Description 


Wide-character 


S) Byte 


Wide-character 


% 


If an | (lowercase ell) does not precede the s specifier, then 
the specifier converts an array of multibyte characters, as 

if by calling mbrtowc for each multibyte character, and 
writes the resulting characters until a null wide character 

is encountered or the number of wide characters indicated 

by the precision specification is exhausted. If the precision 
specification is omitted or is greater than the size of the array 
of converted characters, then the converted array must be 
terminated by a null wide character. 


If an | precedes this conversion specifier, then the argument 
is a pointer to an array of wchar_t. Characters from this 
array are written until a null wide character is encountered 
or the number of wide characters indicated by the precision 
specification is exhausted. If the precision specification is 
omitted or is greater than the size of the array, then the array 
must be terminated by a null wide character. 


Converts an array of wide-character codes to multibyte 
characters, and writes the multibyte characters. Requires 
an argument that is a pointer to an array of wide characters 
of type wchar_t. Characters are written until a null wide 
character is encountered or until the number of bytes 
indicated by the precision specification is exhausted. If 

the precision specification is omitted or is greater than the 
size of the array of converted bytes, then the array of wide 
characters must be terminated by a null wide character. 


The argument is a pointer to an array of wchar t. 
Characters from this array are written until a null wide 
character is encountered or the number of wide characters 
indicated by the precision specification is exhausted. If the 
precision specification is omitted or is greater than the size of 
the array, then the array must be terminated by a null wide 
character. 


Requires an argument that is a pointer to void. The value of 
the pointer is output as a hexadecimal number. 


Requires an argument that is a pointer to an integer. The 
integer is assigned the number of characters written to the 
output stream so far by this call to the formatted output 
function. No argument is converted. 


Writes out the percent symbol. No conversion is performed. 
The complete conversion specification would be %%. 


lRither byte or wide-character. Where neither is shown for a given specifier, the specifier description 


applies to both. 


2.5 Terminal I/O 


HP C defines three file pointers that allow you to perform I/O to and from 

the logical devices usually associated with your terminal (for interactive jobs) 

or a batch stream (for batch jobs). In the OpenVMS environment, the three 
permanent process files SYS$INPUT, SYS$OUTPUT, and SYS$ERROR perform 
the same functions for both interactive and batch jobs. Terminal I/O refers to 
both terminal and batch stream I/O. The file pointers stdin, stdout, and stderr 
are defined when you include the <stdio.h> header file using the #include 


preprocessor directive. 


Understanding Input and Output 2-19 


The stdin file pointer is associated with the terminal to perform input. This 
file is equivalent to SYS$INPUT. The stdout file pointer is associated with the 
terminal to perform output. This file is equivalent to SYS$OUTPUT. The stderr 
file pointer is associated with the terminal to report run-time errors. This file is 
equivalent to SYS$ERROR. 


There are three file descriptors that refer to the terminal. The file descriptor 0 is 
equivalent to SYS$INPUT, 1 is equivalent to SYS$OUTPUT, and 2 is equivalent 
to SYS$ERROR. 


When performing I/O at the terminal, you can use Standard I/O functions and 
macros (specifying the pointers stdin, stdout, or stderr as arguments), you can 
use UNIX I/O functions (giving the corresponding file descriptor as an argument), 
or you can use the Terminal I/O functions and macros. There is no functional 
advantage to using one type of I/O over another; the Terminal I/O functions might 
save keystrokes since there are no arguments. 


2.6 Program Examples 


This section gives some program examples that show how the I/O functions can 
be used in applications. 


Example 2-1 shows the printf function. 


Example 2-1 Output of the Conversion Specifications 


/* CHAP 2 OUT _CONV.C */ 


/* This program uses the printf function to print the */ 
/* various conversion specifications and their effect */ 
/* on the output. */ 


/* Include the proper header files in case printf has */ 
/* to return EOF. */ 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 


#define WIDE STR SIZE 20 


main () 


double val = 123345.5; 


char c = 'C’; 

int i = -1500000000; 
char *s = "thomasina"; 
wchar t wc; 


wchar t ws[WIDE STR SIZE]; 
/* Produce a wide character and a wide character string */ 


if (mbtowc(&wc, "W", 1) == -1) { 
perror ("mbtowc") ; 
exit (EXIT_FAILURE) ; 


if (mbstowcs(ws, "THOMASINA", WIDE STR SIZE) == -1) { 
perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


(continued on next page) 


2-20 Understanding Input and Output 


Example 2-1 (Cont.) Output of the Conversion Specifications 


/* Print the specification code, a colon, two tabs, and the 
/* formatted output value delimited by the angle bracket 
/* characters (<>). 


printf ("$%9.4£:\t\t<%9.4f>\n", val); 
printf ("$39f:\t\t<%9f>\n", val); 

printf ("$%9.0£:\t\t<%9.0f>\n", val); 
printf ("$%-9.0f:\t\t<%-9.0f>\n\n", val); 
printf ("$%11.6e:\t\t<%11.6e>\n", val); 
printf ("$%lle:\t\t<%lle>\n", val); 

printf ("$%11.0e:\t\t<%11.0e>\n", val); 
printf ("$%-11.0e:\t\t<%-11.0e>\n\n", val); 
printf ("$%311lg:\t\t<%llg>\n", val); 

printf ("$%9g:\t\t<%9g>\n\n", val); 

printf ("$%d:\t\t<%d>\n", ¢c); 

printf ("$%c:\t\t<%c>\n", ¢c); 

printf ("$%o0:\t\t<%o>\n", ¢c); 

printf ("$%x:\t\t<%x>\n\n", c); 

printf ("$%d:\t\t<%d>\n", i); 

printf ("$%u:\t\t<%u>\n", i); 

printf ("$%x:\t\t<%x>\n\n", i); 

printf ("$%s:\t\t<%s>\n", 8s); 

printf ("$%-9.6s:\t\t<%-9.6s>\n", 8s); 
printf ("$%-*.*s:\t\t<%-*.*s>\n", 9, 5, 8); 
printf ("$%6.0s:\t\t<%6.0s>\n\n", s); 
printf ("$%C:\t\t<%C>\n", we); 

printf ("$%S:\t\t<%S>\n", ws); 

printf ("$%-9.6S:\t\t<%-9.6S>\n", ws); 
printf ("$%-*.*S:\t\t<$-*.*S>\n", 9, 5, ws); 
printf ("$%6.0S:\t\t<%6.0S>\n\n", ws); 


} 


Running Example 2-1 produces the following output: 


$ RUN EXAMPLE 
$9.4f: 

S9f: 

$9.0f: 

$-9.0f: 


$11.6e: 
$lle: 
$11.0e: 
$-11.0e: 


<123345.5000> 
<123345.500000> 
< 123346> 
<123346 > 


<1.233455e+05> 
<1.233455e+05> 
< 1e+05> 
<1le+05 > 


< 123346> 
123346> 


<67> 
<C> 
<103> 
<43> 


<-1500000000> 
<2794967296> 
<a697d100> 


<thomasina> 
<thomas S 
<thoma > 
< > 
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SC: <W> 
S 


%S: <THOMASINA> 
$-9.6S: <THOMAS > 
S-* *S: <THOMA > 
6.08: < > 


tn oe 


Example 2—2 shows the use of the fopen, ftell, sprintf, fputs, fseek, fgets, 
and fclose functions. 


Example 2-2 Using the Standard I/O Functions 


/* CHAP 2 STDIO.C */ 


/* This program establishes a file pointer, writes lines from */ 
/* a buffer to the file, moves the file pointer to the second */ 
/* record, copies the record to the buffer, and then prints */ 
/* the buffer to the screen. */ 


#include <stdio.h> 
#include <stdlib.h> 


main () 
{ 
char buffer [32]; 
int i, 
pos; 
FILE *fptr; 


/* Set file pointer. */ 
fptr = fopen("data.dat", "w+"); 
if (fptr == NULL) { 

perror ("fopen") ; 

exit (EXIT_FAILURE) ; 


for (i = 1; 1 < 5; i++) { 
) /* Get position of record 2. */ 
pos = ftell(fptr) ; 
/* Print a line to the buffer. */ 
sprintf (buffer, "test data line %d\n", i); 
/* Print buffer to the record. */ 


fputs (buffer, fptr) ; 

} 

/* Go to record number 2. */ 

if (fseek(fptr, pos, 0) < 0) { 
perror("fseek") ; /* Exit on fseek error. */ 
exit (EXIT_FAILURE) ; 

} 

/* Read record 2 in the buffer. */ 

if (fgets(buffer, 32, fptr) == NULL) { 
perror ("fgets") ; /* Exit on fgets error. */ 
exit (EXIT_FAILURE) ; 

/* Print the buffer. */ 

printf("Data in record 2 is: %s", buffer); 

fclose(fptr) ; /* Close the file. */ 


} 


Running Example 2-2 produces the following result: 


S$ RUN EXAMPLE 
Data in record 2 is: test data line 2 
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The output to DATA.DAT from Example 2-2 is: 


test data line 1 
test data line 2 
test data line 3 
test data line 4 


Example 2-3 Using Wide Character I/O Functions 


/* 


CHAP 2 WC_I0.C 


/* This program establishes a file pointer, writes lines from */ 
/* a buffer to the file using wide-character codes, moves the */ 
/* file pointer to the second record, copies the record to the */ 
/* wide-character buffer, and then prints the buffer to the */ 
/* screen. 


#include <stdio.h> 
#include <stdlib.h> 
#include <wchar.h> 


main () 


{ 


char flat_buffer [32]; 
wchar_t wide buffer [32]; 
wcehar_t format [32] ; 


int 


/* 


for 


} 


/* 


Ly 
pos; 


FILE *fptr; 


Set file pointer. */ 


fptr = fopen("data.dat", "w+"); 
if (fptr == NULL) { 


perror("fopen") ; 
exit (EXIT_FAILURE) ; 


if (i == 2) /* Get position of record 2. */ 


pos = ftell(fptr 
/* Print a line to the buffer. 


ei 


sprintf (flat buffer, "test data line ¢d\n", i); 
if (mbstowcs (wide buffer, flat buffer, 32) == -1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


} 


/* Print buffer to the record. */ 
fputws (wide buffer, fptr) ; 
Go to record number 2. */ 
if (fseek(fptr, pos, 0) < 0) { 
perror ("fseek") ; /* Exit on fseek error. */ 


exit (EXIT_FAILURE) ; 
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Example 2-3 (Cont.) Using Wide Character I/O Functions 


/* Put record 2 in the buffer. */ 

if (fgetws(wide buffer, 32, fptr) == NULL) { 
perror ("fgetws") ; /* Exit on fgets error. */ 
exit (EXIT_FAILURE) ; 


/* Print the buffer. */ 
printf("Data in record 2 is: %S", wide buffer) ; 
fclose(fptr) ; /* Close the file. */ 


} 


Running Example 2-3 produces the following result: 


S RUN EXAMPLE 
Data in record 2 is: test data line 2 


The output to DATA.DAT from Example 2-3 is: 


test data line 1 
test data line 2 
test data line 3 
test data line 4 


Example 2—4 shows the use of both a file pointer and a file descriptor to access a 
single file. 
Example 2-4 I/O Using File Descriptors and Pointers 


/* CHAP 2 FILE DIS AND POINTER.C */ 


/* The following example creates a file with variable-length */ 
/* records (rfm=var) and the carriage-return attribute (rat=cr) .*/ 


/* The program uses creat to create and open the file, and */ 
/* fdopen to associate the file descriptor with a file pointer. */ 
/* After using the fdopen function, the file must be referenced */ 
/* using the Standard I/O functions. */ 


include <unixio.h> 
include <stdio.h> 
include <stdlib.h> 
include <string.h> 
define ERROR 0 
define ERROR1 -1 
define BUFFSIZE 132 


main () 


char buffer [BUFFSIZE] ; 
int fildes; 
FILE *fp; 


if ((fildes = creat ("data.dat", 0, "rat=cr", 
"rfm=var")) == ERROR1) { 
perror("DATA.DAT: creat() failed\n") ; 
exit (EXIT_FAILURE) ; 
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Example 2-4 (Cont.) I/O Using File Descriptors and Pointers 


if ((fp = fdopen(fildes, "w")) == NULL) { 
perror("DATA.DAT: fdopen() failed\n") ; 
exit (EXIT_FAILURE) ; 


while (fgets(buffer, BUFFSIZE, stdin) != NULL) 
if (fwrite(buffer, strlen(buffer), 1, fp) == ERROR) { 
perror("DATA.DAT: fwrite() failed\n"); 
exit (EXIT_FAILURE) ; 


if (fclose(fp) == EOF) { 
perror("DATA.DAT: fclose() failed\n") ; 
exit (EXIT_FAILURE) ; 
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3 


Character, String, and Argument-List Functions 


Table 3-1 describes the character, string, and argument-list functions in the HP C 
Run-Time Library (RTL). Although further discussion follows in this chapter, see 
the Reference Section for more detailed information on each function. 


Table 3-1 Character, String, and Argument-List Functions 


Function Description 


Character Classification 


isalnum, iswalnum Returns a nonzero integer if its argument is one of the 
alphanumeric characters in the current locale. 

isalpha, iswalpha Returns a nonzero integer if its argument is one of the 
alphabetic characters in the current locale. 

isascii Returns a nonzero integer if its argument is any ASCII 
character. 

iscntrl, iswentrl Returns a nonzero integer if its argument is a control character 
in the current locale. 

isdigit, iswdigit Returns a nonzero integer if its argument is a digit character 
in the current locale. 

isgraph, iswgraph Returns a nonzero integer if its argument is a graphic 
character in the current locale. 

islower, iswlower Returns a nonzero integer if its argument is a lowercase 
character in the current locale. 

isprint, iswprint Returns a nonzero integer if its argument is a printing 
character in the current locale. 

ispunct, iswpunct Returns a nonzero integer if its argument is a punctuation 
character in the current locale. 

isspace, iswspace Returns a nonzero integer if its argument is a white-space 
character in the current locale. 

isupper, iswupper Returns a nonzero integer if its argument is an uppercase 
character in the current locale. 

iswctype Returns a nonzero integer if its argument has the specified 
property. 

isxdigit, iswxdigit Returns a nonzero integer if its argument is a hexadecimal 


digit (0 to 9, A to F, or a to f). 
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Table 3-1 (Cont.) Character, String, and Argument-List Functions 


Function 


Description 


Character Conversion 


btowc 
ecvt, fevt, gevt 


index, rindex 
mblen, mbrlen 
mbsinit 

mbstowcs 

toascil 

tolower, tolower, 


towlower 
toupper, toupper, 
towupper 
towctrans 


wcestombs 


wctob 


wctomb 


wctrans 


wcetype 


Converts a one-byte multibyte character to a wide character in 
the initial shift state. 


Converts an argument to a null-terminated string of ASCII 
digits and return the address of the string. 


Searches for a character in a string. 
Determines the number of bytes in a multibyte character. 


Determines whether an mbstate_t object decribes an initial 
conversion state. 


Converts a sequence of multibyte characters into a sequence of 
corresponding codes. 


Converts its argument, an 8-bit ASCII character, to a 7-bit 
ASCII character. 


Converts its argument, an uppercase character, to lowercase. 
Converts its argument, a lowercase character, to uppercase. 


Maps one wide character to another according to a specified 
mapping descriptor. 


Converts a sequence of wide-character codes corresponding to 
multibyte characters to a sequence of multibyte characters. 


Determines if a wide character corresponds to a single-byte 
multibyte character and returns its multibyte character 
representation. 


Converts a wide character to its multibyte character 
representation. 


Returns the description of a mapping, corresponding to 
specified property, that can be later used in a call to 
towctrans. 


Converts a valid character class defined for the current locale 
to an object of type wctype t. 


String Manipulation 


atof 
atoi, atol 


atoll, atog (Alpha, 164) 
basename 
dirname 


strcat, strncat, 
wescat, wcsncat 


strchr, strrchr, 
weschr, wesrchr 


Converts a given string to a double-precision number. 


Converts a given string of ASCII characters to the appropriate 
numeric values. 


Converts a given string of ASCII characters toan __inté4. 
Returns the last component of a path name. 
Reports the parent directory name of a file path name. 


Appends one string to the end of another string. 


Returns the address of the first or last occurrence of a given 
character in a null-terminated string. 
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Table 3-1 (Cont.) Character, String, and Argument-List Functions 


Function 


Description 


String Manipulation 


strcmp, strncemp, 
strcoll, wcscmp, 
wcesnemp, wcescoll 


strcpy, strncpy, 
wcscpy, wcesncpy 
strxfrm, wcsxfrm 
strcspn, wcscspn 
strlen, wcslen 

strpbrk, wcspbrk 
strspn, wcsspn 


strstr, wcswcs 


strtod, wcstod 
strtok, wcestok 
strtol, westol 


strtoll, strtoq 
(Alpha, I64) 


strtoul, wcstoul 


strtoull, strtoug 
(Alpha, I64) 


Compares two character strings and returns a negative, zero, 

or positive integer indicating that the values of the individual 
characters in the first string are less than, equal to, or greater 
than the values in the second string. 


Copies all or part of one string into another. 


Transforms a multibyte string to another string ready for 
comparisons using the strcmp or wcscmp function. 


Searches a string for a character that is in a specified set of 
characters. 


Returns the length of a string of characters. The returned 
length does not include the terminating null character (\0). 


Searches a string for the occurrence of one of a specified set of 
characters. 


Searches a string for the occurrence of a character that is not 
in a specified set of characters. 


Searches a string for the first occurrence of a specified set of 
characters. 


Converts a given string to a double-precision number. 
Locates text tokens in a given string. 
Converts the initial portion of a string to a signed long integer. 


Converts the initial portion of a string to signed _inté4. 


Converts the initial portion of a string to an unsigned long 
integer. 


Converts the initial portion of the string pointed to by the 
pointer to the character string to an unsigned __ int 64. 


String Handling—Accessing Binary Data 


bemp 
bcopy 
bzero 
memchr, wmemchr 


memcmp, wmemcmp 


memcpy, memmove, 
wmemcpy, wmemmove 


memset, wmemset 


Compares byte strings. 
Copies byte strings. 
Copies nulls into byte strings. 


Locates the first occurrence of the specified byte within the 
initial length of the object to be searched. 


Compares two objects byte by byte. 


Copies a specified number of bytes from one object to another. 
Sets a specified number of bytes in a given object to a given 


value. 
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Table 3-1 (Cont.) Character, String, and Argument-List Functions 


Function Description 


Argument-List Handling—Accessing a Variable-Length Argument List 


va_arg Returns the next item in the argument list. 

va_count Returns the number of longwords (VAX only) or quadwords 
(Alpha only) in the argument list. 

va_end Finishes the va_start session. 

va_start, Initializes a variable to the beginning of the argument list. 

va_start_l 

vfprintf, vprintf, Prints formatted output based on an argument list. 

vsprintf 


3.1 Character-Classification Functions 


The character-classification functions take a single argument on which they 
perform a logical operation. The argument can have any value; it does not have 
to be an ASCII character. The isascii function determines if the argument is an 
ASCII character (0 through 177 octal). The other functions determine whether 
the argument is a particular type of ASCII character, such as a graphic character 
or digit. The isw* functions test wide characters. Character-classification 
information is in the LC_CTYPE category of the program’s current locale. 


For all functions, a positive return value indicates TRUE. A return value of 0 
indicates FALSE. 


To briefly reference the character-classification functions in a subsequent table, 
each function is assigned a number, as shown in Table 3-2. 


Table 3-2 Character-Classification Functions 


Function Function 

Number Function Number Function 
1 isalnum 7 islower 
2 isalpha 8 isprint 
3 isascii 9 ispunct 
4 iscntrl 10 isspace 
5 isdigit 11 isupper 
6 isgraph 12 isxdigit 


Table 3-3 lists the numbers of the functions (as assigned in Table 3—2) that 
return the value TRUE for each of the given ASCII characters. The numeric code 
represents the octal value of each of the ASCII characters. 
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Table 3-3 ASCII Characters and the Character-Classification Functions 


ASCII Function ASCII Function 
Values Numbers Values Numbers 
NUL 00 3,4 @ 100 3,6,8,9 

SOH 01 3,4 A101 1,2,3,6,8,11,12 
STX 02 3,4 B 102 1,2,3,6,8,11,12 
ETX 03 3,4 C 103 1,2,3,6,8,11,12 
EOT 04 3,4 D 104 1,2,3,6,8,11,12 
ENQ 05 3,4 E 105 1,2,3,6,8,11,12 
ACK 06 3,4 F 106 1,2,3,6,8,11,12 
BEL 07 3,4 G 107 1,2,3,6,8,11 
BS 10 3,4 H 110 1,2,3,6,8,11 
HT 11 3,4,10 1111 1,2,3,6,8,11 
LF 12 3,4,10 J 112 1,2,3,6,8,11 
VT 13 3,4,10 K 113 1,2,3,6,8,11 
FF 14 3,4,10 L 114 1,2,3,6,8,11 
CR 15 3,4,10 M 115 1,2,3,6,8,11 
SO 16 3,4 N 116 1,2,3,6,8,11 
SI 17 3,4 O 117 1,2,3,6,8,11 
DLE 20 3,4 P 120 1,2,3,6,8,11 
DC1 21 3,4 Q 121 1,2,3,6,8,11 
DC2 22 3,4 R 122 1,2,3,6,8,11 
DC3 23 3,4 S 123 1,2,3,6,8,11 
DC4 24 3,4 T 124 1,2,3,6,8,11 
NAK 25 3,4 U 125 1,2,3,6,8,11 
SYN 26 3,4 V 126 1,2,3,6,8,11 
ETB 27 3,4 W 127 1,2,3,6,8,11 
CAN 30 3,4 X 180 1,2,3,6,8,11 
EM 31 3,4 Y 131 1,2,3,6,8,11 
SUB 32 3,4 Z 182 1,2,3,6,8,11 
ESC 33 3,4 [ 133 3,6,8,9 

FS 34 3,4 \ 134 3,6,8,9 

GS 35 3,4 ] 135 3,6,8,9 

RS 36 3,4 * 136 3,6,8,9 

US 37 3,4 — 137 3,6,8,9 

SP 40 3,8,10 ~ 140 3,6,8,9 

! 41 3,6,8,9 a 141 1,2,3,6,7,8,12 


(continued on next page) 
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Table 3-3 (Cont.) ASCII Characters and the Character-Classification Functions 


ASCII Function ASCII Function 
Values Numbers Values Numbers 

" AQ 3,6,8,9 b 142 1,2,3,6,7,8,12 
# 43 3,6,8,9 c 148 1,2,3,6,7,8,12 
$ 44 3,6,8,9 d 144 1,2,3,6,7,8,12 
% 45 3,6,8,9 e 145 1,2,3,6,7,8,12 
& 46 3,6,8,9 f 146 1,2,3,6,7,8,12 
' AT 3,6,8,9 g 147 1,2,3,6,7,8 
(50 3,6,8,9 h 150 1,2,3,6,7,8 

) 51 3,6,8,9 i151 1,2,3,6,7,8 

* 52 3,6,8,9 j 152 1,2,3,6,7,8 

+ 53 3,6,8,9 k 153 1,2,3,6,7,8 

> 54 3,6,8,9 1154 1,2,3,6,7,8 

- 55 3,6,8,9 m 155 1,2,3,6,7,8 

. 56 3,6,8,9 n 156 1,2,3,6,7,8 
/57 3,6,8,9 0 157 1,2,3,6,7,8 

0 60 1,3,5,6,8,12 p 160 1,2,3,6,7,8 
161 1,3,5,6,8,12 q 161 1,2,3,6,7,8 

2 62 1,3,5,6,8,12 r 162 1,2,3,6,7,8 

3 63 1,3,5,6,8,12 s 163 1,2,3,6,7,8 

4 64 1,3,5,6,8,12 t 164 1,2,3,6,7,8 

5 65 1,3,5,6,8,12 u 165 1,2,3,6,7,8 

6 66 1,3,5,6,8,12 v 166 1,2,3,6,7,8 

7 67 1,3,5,6,8,12 w 167 1,2,3,6,7,8 

8 70 1,3,5,6,8,12 x 170 1,2,3,5,6,8 
971 1,3,5,6,8,12 y 171 1,2,3,5,6,8 

: 72 3,6,8,9 z172 1,2,3,5,6,8 

; 73 3,6,8,9 {173 3,6,8,9 

< 74 3,6,8,9 | 174 3,6,8,9 

= 75 3,6,8,9 } 175 3,6,8,9 

> 76 3,6,8,9 ~ 176 3,6,8,9 

277 3,6,8,9 DEL 177 3,4 
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Example 3—1 shows how the character-classification functions are used. 


Example 3-1 Character-Classification Functions 


/* CHAP 3 CHARCLASS.C */ 
/* This example uses the isalpha, isdigit, and isspace */ 
/* functions to count the number of occurrences of letters, * / 
/* digits, and white-space characters entered through the */ 
/* standard input (stdin). * / 


#include <ctype.h> 
#include <stdio.h> 
#include <stdlib.h> 


main () 


{ 


while ((c = getchar()) != EOF) { 
if (isalpha(c) ) 
i++; 
if (isdigit(c) ) 
jtt; 
if (isspace(c) ) 
k++; 


} 


printf ("Number of letters: %d\n", i); 
printf("Number of digits: $%d\n", j); 
printf ("Number of spaces: %d\n", k); 


} 


The sample input and output from Example 3-1 follows: 


$ RUN EXAMPLE1 

I saw 35 people riding bicycles on Main Street. [Retum] 
em 
Number of letters: 36 
Number of digits: 2 
Number of spaces: 8 


$ 


3.2 Character-Conversion Functions 


The character-conversion functions convert one type of character to another type. 
These functions include: 


ecvt _tolower 
Ecvt toupper 
gevt _toupper 
mbtowc towctrans 
mbrtowc wetrans 
mbsrtowcs wertomb 
toascil wcesrtombs 
tolower 


For more information on each of these functions, see the Reference Section. 
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Example 3—2 shows how to use the ecvt function. 


Example 3-2 Converting Double Values to an ASCII String 


/* CHAP 3 CHARCONV.C 


/* This program uses the ecvt function to convert a double 
/* value to a string. The program then prints the string. 


#include <stdio.h> 

#include <stdlib.h> 
#include <unixlib.h> 
#include <string.h> 


main () 
{ 


double val; /* Value to be converted */ 


int sign, /* Variables for sign */ 
point; /* and decimal place */ 


/* Array for the converted string */ 
static char string[20]; 


val = -3.1297830e-10; 


printf ("original value: %e\n", val); 
if (sign) 
printf ("value is negative\n") ; 
else 
printf ("value is positive\n") ; 
printf ("decimal point at %d\n", point); 


} 


The output from Example 3-2 is as follows: 


$ RUN EXAMPLE2 

original value: -3.129783e-10 
converted string: 31298 

value is negative 

decimal point at -9 


$ 


ep 


*/ 
ai 


Example 3—3 shows how to use the toupper and tolower functions. 


Example 3-3 Changing Characters to and from Uppercase Letters 


/* CHAP 3 CONV _UPPERLOWER.C 


/* This program uses the functions toupper and tolower to 
/* convert uppercase to lowercase and lowercase to uppercase 
/* using input from the standard input (stdin). 


#include <ctype.h> 
#include <stdio.h> /* To use EOF identifier */ 
#include <stdlib.h> 


main () 


{ 


char c, 
ch; 


*f 


(continued on next page) 
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Example 3-3 (Cont.) Changing Characters to and from Uppercase Letters 


while ((c = getchar()) != EOF) { 
if (c >= ‘A’ && c <= 'Z') 
ch = tolower(c); 
else 
ch = toupper(c) ; 
putchar (ch) ; 


} 
} 


Sample input and output from Example 3-3 are as follows: 


$ RUN EXAMPLE3 
LET’S GO TO THE welcome INN. [ci/z 
let's go to the WELCOME inn. 


3.3 String and Argument-List Functions 


The HP C RTL contains a group of functions that manipulate strings. Some of 
these functions concatenate strings; others search a string for specific characters 
or perform some other comparison, such as determining the equality of two 
strings. 


The HP C RTL also contains a set of functions that allow you to copy buffers 
containing binary data. 


The set of functions defined and declared in the <varargs.h> and the <stdarg.h> 
header files provide a method of accessing variable-length argument lists. The 
<stdarg.h> functions are defined by the ANSI C Standard and are more portable 
than those defined in <varargs.h>. 


The RTL functions such as printf and execl, for example, use variable-length 
argument lists. User-defined functions with variable-length argument lists that 
do not use <varargs.h> or <stdarg.h> are not portable due to the different 
argument-passing conventions of various machines. 


The <stdarg.h> header file does not contain va_alist and va_dcl. The following 
shows a syntax example when using <stdarg.hs>: 


function_name(int arg’, ...) 


{ 


va_list ap; 


When using <varargs.h>: 
e The identifier va_alist is a parameter in the function definition. 


e va_dcl declares the parameter va_alist, a declaration that is not terminated 
with a semicolon (;). 


e The type va_list is used in the declaration of the variable used to traverse 
the list. You must declare at least one variable of type va_list when using 
<varargs.h>. 
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These names and declarations have the following syntax: 


function_name(int arg?, ... ) 


{ 


va_list ap; 


3.4 Program Examples 


Example 3—4 shows how to use the strcat and strncat functions. 


Example 3-4 Concatenating Two Sirings 


/* CHAP 3 CONCAT.C */ 


/* This example uses strcat and strncat to concatenate two */ 
/* strings. */ 


#include <stdio.h> 
#include <string.h> 


main () 
static char string1[80] = "Concatenates "; 
static char string2[] = "two strings "; 
static char string3[] = "up to a maximum of characters."; 
static char string4[] = "imum number of characters"; 
printf ("streat:\t%s\n", strceat(stringl, string2)); 
printf ("strncat ( 0):\t%s\n", strncat(stringl, string3, 0)); 
printf ("strncat (11):\t%s\n", strncat(stringl, string3, 11)); 
printf ("strncat (40):\t%s\n", strncat(stringl, string4, 40)); 


} 


Example 3—4 produces the following output: 


$ RUN EXAMPLE1 

strcat: Concatenates two strings 

strncat ( 0): Concatenates two strings 

strncat (11): Concatenates two strings up to a max 

strncat (40): Concatenates two strings up to a maximum number of characters. 


$ 


Example 3-5 shows how to use the strcspn function. 


Example 3-5 Four Arguments to the strcspn Function 


/* CHAP 3 STRCSPN.C */ 
/* This example shows how strcspn interprets four */ 
/* different kinds of arguments. */ 


#include <stdio.h> 


main () 
{ 


printf ("strespn with null charset: %d\n", 
strespn("abcdef", "")); 


(continued on next page) 
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Example 3-5 (Cont.) Four Arguments to the strcspn Function 
printf ("strespn with null string: %d\n", 
strespn("", "abcdef")); 


printf ("strespn(\"xabe\", \"abc\"): %d\n", 
strespn("xabe", "abe")); 


printf ("strespn(\"abc\", \"def\"): %d\n", 
strespn("abc", "def")); 
} 


The sample output, to the file strcspn.out, in Example 3-5 is as follows: 


$ RUN EXAMPLE2 


strcespn with null charset: 6 
strcspn with null string: 0 
strespn("xabe","abe"): 1 
strespn("abc","def"): 3 


Example 3-6 shows how to use the <stdarg.h> functions and definitions. 


Example 3-6 Using the <stdarg.h> Functions and Definitions 


/* CHAP 3 STDARG.C */ 
/* This routine accepts a variable number of string arguments, */ 
/* preceded by a count of the number of such strings. It */ 
/* allocates enough space in which to concatenate all of the */ 


/* strings, concatenates them together, and returns the address */ 
/* of the new string. It returns NULL if there are no string */ 


/* arguments, or if they are all null strings. */ 
#include <stdarg.h> /* Include appropriate header files */ 
#include <stdlib.h> /* for the "example" call in main. */ 


#include <string.h> 
#include <stdio.h> 


/* NSTRINGS is the maximum number of string arguments accepted */ 
/* (arbitrary) . */ 


#define NSTRINGS 10 


char *concatenate(int n,...) 


va_list ap; /* Declare the argument pointer. */ 
char *list [NSTRINGS] , 
*string; 
int index = 0, 
size = 0; 
/* Check that the number of arguments is within range. */ 
if (n <= 0) 
return NULL; 
if (n > NSTRINGS) 
n = NSTRINGS; 
va_start(ap, n); /* Initialize the argument pointer. */ 


do { 
/* Extract the next argument and save it. */ 
list [index] = va_arg(ap, char *); 


(continued on next page) 
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Example 3-6 (Cont.) Using the <stdarg.h> Functions and Definitions 
size += strlen(list [index] ) ; 
} while (++index < n); 
va_end(ap); /* Terminate use of ap. */ 


if (size == 0) 
return NULL; 


string = malloc(size + 1); 
string[0] = ‘\0'; 


/* Append each argument to the end of the growing result */ 
/* string. */ 
for (index = 0; index < n; ++index) 

strceat (string, list [index]) ; 


return string; 


/* An example of calling this routine is */ 


main() { 
char *ret_string ; 
ret_string = concatenate(7, "This ", "message ", "is ", 
"built with ", "a", " variable arg", 
WTst.") 


puts(ret_string) ; 


The call to Example 3-6 produces the following output: 


This message is built with a variable arg list. 
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4 


Error and Signal Handling 


Table 4—1 lists and describes all the error- and signal-handling functions found 
in the HP C Run-Time Library (RTL). For more detailed information on each 
function, see the Reference Section. 


Table 4-1 Error- and Signal-Handling Functions 


Function Description 

abort Raises the signal SIGABRT that terminates the execution of 
the program. 

assert Puts diagnostics into programs. 

atexit Registers a function to be called at program termination. 


exit, exit 


perror 


strerror 
alarm 


gsignal 
kill 


long jmp 


pause 
raise 
setjmp 


sigaction 
sigaddset 
sigblock 


sigdelset 


sigemptyset 


sigfillset 
sighold 
sigignore 


Terminates the current program. 


Writes a short error message to stderr describing the current 
errno value. 


Maps the error code in errno to an error message string. 


Sends the signal SIGALARM to the invoking process after the 
number of seconds indicated by its argument has elapsed. 


Generates a specified software signal. 


Sends a SIGKILL signal to the process specified by a 
process ID. 


Transfers control from a nested series of function invocations 
back to a predefined point without returning normally. 


Causes the process to wait until it receives a signal. 
Generates a specified signal. 


Establishes the context for a later transfer of control from 
a nested series of function invocations, without returning 
normally. 


Specifies the action to take upon delivery of a signal. 
Adds the specified individual signal. 


Causes the signals in its argument to be added to the current 
set of signals being blocked from delivery. 


Deletes a specified individual signal. 

Initializes the signal set to exclude all signals. 

Initializes the signal set to include all signals. 

Adds the specified signal to the calling process’s signal mask. 
Sets the disposition of the specified signal to SIG_IGN. 


(continued on next page) 
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Table 4-1 (Cont.) Error- and Signal-Handling Functions 


Function Description 

sigismember Tests whether a specified signal is a member of the signal set. 

siglongjmp Nonlocal goto with signal handling. 

sigmask Constructs the mask for a given signal number. 

signal Catches or ignores a signal. 

sigpause Blocks a specified set of signals and then waits for a signal 
that was not blocked. 

sigpending Examines pending signals. 

sigprocmask Sets the current signal mask. 

sigrelse Removes the specified signal from the calling process’s signal 
mask. 

sigsetjmp Sets the jump point for a nonlocal goto. 

sigsetmask Establishes the signals that are blocked from delivery. 

sigstack Defines an alternate stack on which to process signals. 

sigsuspend Atomically changes the set of blocked signals and waits for a 
signal. 

sigtimedwait Suspends a calling thread and waits for queued signals to 
arrive. 

sigvec Permanently assigns a handler for a specific signal. 

sigwait Suspends a calling thread and waits for queued signals to 
arrive. 

sigwaitinfo Suspends a calling thread and waits for queued signals to 
arrive. 

ssignal Allows you to specify the action to be taken when a particular 
signal is raised. 

VAXCSESTABLISH Establishes an application exception handler in a way that is 


compatible with HP C RTL exception handling. 


4.1 Error Handling 


When an error occurs during a call to any of the HP C RTL functions, the 
function returns an unsuccessful status. Many RTL routines also set the external 
variable errno to a value that indicates the reason for the failure. You should 
always check the return value for an error situation. 


The <errno.h> header file declares errno and symbolically defines the possible 
error codes. By including the <errno.h> header file in your program, you can 
check for specific error codes after a HP C RTL function call. 


At program startup, the value of errno is 0. The value of errno can be set to a 
nonzero value by many HP C RTL functions. It is not reset to 0 by any HP C 
RTL function, so it is only valid to use errno after a HP C RTL function call has 
been made and a failure status returned. Table 4—2 lists the symbolic values that 
may be assigned to errno by the HP C RTL. 
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Table 4-2 The Error Code Symbolic Values 


Symbolic Constant 


Description 


E2BIG 

EACCES 
EADDRINUSE 
EADDRNOTAVAIL 
EAFNOSUPPORT 
EAGAIN 

EALIGN 
EALREADY 
EBADF 
EBADCAT 
EBADMSG 
EBUSY 
ECANCELED 
ECHILD 
ECONNABORTED 
ECONNREFUSED 
ECONNRESET 
EDEADLK 
EDESTADDRREQ 
EDOM 

EDQUOT 

EEXIST 

EFAIL 

EFAULT 

EFBIG 

EFTYPE 
EHOSTDOWN 
EHOSTUNREACH 
EIDRM 

EILSEQ 
EINPROGRESS 
EINPROG 

EINTR 

EINVAL 

EIO 

EISCONN 

EISDIR 

ELOOP 


Argument list too long 
Permission denied 

Address already in use 

Can’t assign requested address 
Address family not supported 

No more processes 

Alignment error 

Operation already in progress 
Bad file number 

Bad message catalog format 
Corrupted message detected 
Mount device busy 

Operation canceled 

No children 

Software caused connection abort 
Connection refused 

Connection reset by peer 
Resource deadlock avoided 
Destination address required 
Math argument 

Disk quota exceeded 

File exists 

Cannot start operation 

Bad address 

File too large 

Inappropriate operation for file type 
Host is down 

No route to host 

Identifier removed 

Illegal byte sequence 

Operation now in progress 
Asynchronous operation in progress 
Interrupted system call 

Invalid argument 

I/O error 

Socket is already connected 

Is a directory 

Too many levels of symbolic links 


(continued on next page) 


Error and Signal Handling 4-3 


Table 4—2 (Cont.) The Error Code Symbolic Values 


Symbolic Constant 


Description 


EOPNOTSUPP 
EPERM 
EPFNOSUPPORT 
EPIPE 
EPROCLIM 
EPROTONOSUPPORT 
EPROTOTYPE 
ERANGE 
EREMOTE 
EROFS 
ESHUTDOWN 
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Too many open files 

Too many links 

Message too long 

File name too long 
Network is down 

Network dropped connection on reset 
Network is unreachable 
File table overflow 

No buffer space available 
No such device 

No such file or directory 
Exec format error 

No locks available 

Not enough core 

No message of desired type 


Protocol not available 


No space left on device 

Function not implemented 

Block device required 

Socket is not connected 

Not a directory 

Directory not empty 

Socket operation on nonsocket 
Function not implemented 

Not a typewriter 

No waiting processes 

No such device or address 
Operation not supported on socket 
Not owner 

Protocol family not supported 
Broken pipe 

Too many processes 

Protocol not supported 

Protocol wrong type for socket 
Result too large 

Too many levels of remote in path 
Read-only file system 

Can’t send after socket shutdown 


(continued on next page) 


Table 4—2 (Cont.) The Error Code Symbolic Values 


Symbolic Constant Description 
ESOCKTNOSUPPORT Socket type not supported 
ESPIPE Illegal seek 

ESRCH No such process 

ESTALE Stale NFS file handle 
ETIMEDOUT Connection timed out 
ETOOMANYREFS Too many references: can’t splice 
ETXTBSY Text file busy 

EUSERS Too many users 

EVMSERR OpenVMS specific nontranslatable error code 
EWOULDBLOCK I/O operation would block channel 
EXDEV Cross-device link 


You can translate the error codes to a message, similar to that found in UNIX 
systems, by using the perror or strerror function. If errno is set to EVMSERR, 
perror cannot translate the error code and prints the following message, followed 
by the OpenVMS error message associated with the value: 


Ss:nontranslatable vms error code: xxxxxx vms message: 


In the message, %s is the string you supply to perror; xxxxxx is the OpenVMS 
condition value. 


If errno is set to EVMSERR, then the OpenVMS condition value is available in 
the vaxcSerrno variable declared in the <errno.h> header file. The vaxcSerrno 
variable is guaranteed to have a valid value only if errno is set to EVMSERR; 
if errno is set to a value other than EVMSERR, the value of vaxcSerrno is 
undefined. 


See the strerror function in the Reference Section for another way to translate 
error codes. 


4.2 Signal Handling 


A signal is a form of software interrupt to the normal execution of a user process. 
Signals occur as a result of a variety of events, including any of the following: 


e Typing Ctrl/C at a terminal 
e Certain programming errors 
e <Acall to the gsignal or raise function 


e A wake-up action 


4.2.1 OpenVMS Versus UNIX Terminology 


Both OpenVMS and UNIX systems provide signal-handling mechanisms that 
behave differently but use similar terminology. With the HP C RTL, you 
can program using either signal-handling mechanism. Before describing the 
signal-handling routines, some terminology must be established. 


The UNIX term for a software interrupt is signal. A routine called by the UNIX 
system to process a signal is termed a signal handler. 
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A software interrupt on an OpenVMS system is referred to as a signal, condition, 
or exception. A routine called by the OpenVMS system to process software 
interrupts is termed a signal handler, condition handler, or exception handler. 


To prevent confusion, the terms signal and signal handler in this manual refer to 
UNIX interrupts and interrupt processing routines, while the terms exception and 
exception handler refer to OpenVMS interrupts and interrupt processing routines. 


4.2.2 UNIX Signals and the HP C RTL 


Signals are represented by mnemonics defined in the <signal.h> header file. 
Table 4-3 lists the supported signal mnemonics and the corresponding event that 
causes each signal to be generated on the OpenVMS operating system. 


Table 4-3 HP C RTL Signals 


Name Description Generated by 

SIGABRT" Abort abort() 

SIGALRM Alarm clock Timer AST, alarm routine 

SIGBUS Bus error Access violation or change mode user 

SIGCHLD Child process stopped Child process terminated or stopped 

SIGEMT EMT instruction Compatibility mode trap or opcode reserved 

to customer 

SIGFPE Floating-point Floating-point overflow/underflow 
exception 

SIGHUP Hang up Data set hang up 

SIGILL! Illegal Illegal instruction, reserved operand, or 
instruction reserved address mode 

SIGINT* Interrupt OpenVMS Ctrl/C interrupt 

SIGIOT! IOT instruction Opcode reserved to customer 

SIGKILL?,° Kill External signal only 

SIGQUIT® Quit Not implemented. 

SIGPIPE Broken pipe Write to a pipe with no readers. 

SIGSEGV Segment Length violation or change mode user 
violation 

SIGSYS System call Bad argument to system call 
error 

SIGTERM Software External signal only 
terminate 

SIGTRAP! Trace trap TBIT trace trap or breakpoint fault 

instruction 
SIGUSR1 User-defined signal Explicit program call to raise the signal 


1Cannot be reset when caught. 


2Cannot be caught or ignored. 


3Cannot be blocked. 
4Setting SIGINT can affect processing of Ctrl/Y interrupts. For example, in response to a caller’s 
request to block or ignore SIGINT, the HP C RTL disables the Ctrl/Y interrupt. 


5"Not implemented" for SIGQUIT means that there is no external event, including a Ctrl/Y interrupt, 
that would trigger a SIGQUIT signal, thereby causing a signal handler established for SIGQUIT to 
be invoked. This signal can be generated only through an appropriate HP C RTL function, such as 


ralse. 
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Table 4-3 (Cont.) HP C RTL Signals 


Name Description Generated by 
SIGUSR2 User-defined signal Explicit program call to raise the signal 
SIGWINCH® Window size changed Explicit program call to raise the signal 


®Supported on OpenVMS Version 7.3 and higher. 


By default, when a signal (except for SIGCHLD) occurs, the process is terminated. 
However, you can choose to have the signal ignored by using one of the following 
functions: 


sigaction 
signal 
sigvec 
ssignal 


You can have the signal blocked by using one of the following functions: 


sigblock 
sigsetmask 
sigprocmask 
sigsuspend 
sigpause 


Table 4—3 indicates those signals that cannot be ignored or blocked. 


You can also establish a signal handler to catch and process a signal by using one 
of the following functions: 


sigaction 
signal 
sigvec 
ssignal 


Unless noted in Table 4—3, each signal can be reset. A signal is reset if the signal 
handler function calls signal or ssignal to re-establish itself to catch the signal. 
Example 4—1 shows how to establish a signal handler and reset the signal. 


The calling interface to a signal handler is: 
void handler (int sigint); 


Where sigint is the signal number of the raised signal that caused this handler to 
be called. 


A signal handler installed with sigvec remains installed until it is changed. 


A signal handler installed with signal or signal remains installed until the 
signal is generated. 


A signal handler can be installed for more than one signal. Use the sigaction 
routine with the SA_RESETHAND flag to control this. 
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4.2.3 Signal-Handling Concepts 


A signal is said to be generated for (or sent to) a process when the event that 
causes the signal first occurs. Examples of such events include detection of 
hardware faults, timer expiration, and terminal activity, as well as the invocation 
of kill. In some circumstances, the same event generates signals for multiple 
processes. 


Each process has an action to be taken in response to each signal defined by the 
system. A signal is said to be delivered to a process when the appropriate action 
for the process and signal is taken. 


During the time between the generation of a signal and its delivery, the signal is 
said to be pending. Ordinarily, this interval cannot be detected by an application. 
However, a signal can be blocked from delivery to a process: 


e If the action associated with a blocked signal is anything other than to ignore 
the signal, and if that signal is generated for the process, the signal remains 
pending until either it is unblocked or the action associated with it is set to 
ignore the signal. 


e Ifthe action associated with a blocked signal is to ignore the signal and if 
that signal is generated for the process, it is unspecified whether the signal is 
discarded immediately upon generation or remains pending. 


Each process has a signal mask that defines the set of signals currently blocked 
from delivery to it. The signal mask for a process is initialized from that of 

its parent. The sigaction, sigprocmask, and sigsuspend functions control the 
manipulation of the signal mask. 


The determination of which action is taken in response to a signal is made 

at the time the signal is delivered, allowing for any changes since the time of 
generation. This determination is independent of the means by which the signal 
was originally generated. If a subsequent occurrence of a pending signal is 
generated, it is implementation-dependent as to whether the signal is delivered 
more than once. The HP C RTL delivers the signal only once. The order in which 
multiple, simultaneously pending signals are delivered to a process is unspecified. 
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This section applies to the sigaction, signal, sigvec, and ssignal functions. 
There are three types of action that can be associated with a signal: 


SIG_DFL 
SIG_IGN 


pointer to a function 


Initially, all signals are set to SIG_DFL or SIG_IGN prior to entry of the main 
routine (see the exec functions.) The actions prescribed by these values are: 


SIG_DFL — signal-specific default action 


e The default actions for the signals defined in this document are specified 
under <signal .h>. 


e If the default action is to stop the process, the execution of that process 
is temporarily suspended. When a process stops, a SIGCHLD signal 
is generated for its parent process, unless the parent process has set 
the SA_NOCLDSTOP flag. While a process is stopped, any additional 
signals that are sent to the process are not delivered until the process 
is continued, except SIGKILL which always terminates the receiving 
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process. A process that is a member of an orphaned process group is 

not allowed to stop in response to the SIGSTOP, SIGTTIN, or SIGTTOU 
signals. In cases where delivery of one of these signals would stop such a 
process, the signal is discarded. 


e Setting a signal action to SIG_DFL for a signal that is pending and whose 
default action is to ignore the signal (for example, SIGCHLD), causes the 
pending signal to be discarded, whether or not it is blocked. 


SIG_IGN — ignore signal 


e Delivery of the signal has no effect on the process. The behavior of a 
process is undefined after it ignores a SIGFPE, SIGILL, or SIGSEGV 
signal that was not generated by kill or raise. 


e The system does not allow the action for the SIGKILL or SIGSTOP 
signals to be set to SIG_IGN. 


e Setting a signal action to SIG_IGN for a signal that is pending causes the 
pending signal to be discarded, whether or not it is blocked. 


e Ifa process sets the action for the SIGCHLD signal to SIG_IGN, the 
behavior is unspecified. 


pointer to a function — catch signal 


e On delivery of the signal, the receiving process executes the signal- 
catching function at the specified address. After returning from the 
signal-catching function, the receiving process resumes execution at the 
point at which it was interrupted. 


e Specify the signal-catching function as: 
void func(int signo) ; 


Here, func is the specified signal-catching function and signo is the signal 
number of the signal being delivered. 


e The behavior of a process is undefined after it returns normally from a 
signal-catching function for a SIGFPE, SIGKILL, or SIGSEGV signal that 
was not generated by kill or raise. 


e The system does not allow a process to catch the signals SIGKILL and 
SIGSTOP. 


e Ifa process establishes a signal-catching function for the SIGCHLD signal 
while it has a terminated child process for which it has not waited, it is 
unspecified whether a SIGCHLD signal is generated to indicate that child 
process. 


4.2.5 Signal Handling and OpenVMS Exception Handling 


This section discusses how HP C RTL signal handling is implemented with 
and interacts with OpenVMS exception handling. Information in this section 
allows you to write OpenVMS exception handlers that do not conflict with HP C 
RTL signal handling. For information on OpenVMS exception handling, see the 
OpenVMS Procedure Calling and Condition Handling Standard. 
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The HP C RTL implements signals with OpenVMS exceptions. When gsignal 

or raise is called, the signal number is translated to a particular OpenVMS 
exception, which is used in a call to LIB$SIGNAL. This mechanism is necessary 
to catch an OpenVMS exception resulting from a user error and translate it into 
a corresponding UNIX signal. For example, an ACCVIO resulting from a write to 
a NULL pointer is translated to a SIGBUS or SIGSEGV signal. 


Tables 4—4, 4-5, and 4-6 list the HP C RTL signal names, the corresponding 
OpenVMS VAX, Alpha, and I64 exceptions, the event that generates the signal, 
and the optional signal code for use with the gsignal and raise functions. 


Table 4-4 HP C RTL Signals and Corresponding OpenVMS VAX Exceptions (vax only) 


Name OpenVMS Exception Generated By Code 

SIGABRT SS$_OPCCUS The abort function = 

SIGALRM SS$_ASTFLT The alarm function - 

SIGBUS SS$_ACCVIO Access violation — 

SIGBUS SS$_CMODUSER Change mode user - 

SIGCHLD C$_SIGCHLD Child process stopped - 

SIGEMT SS$_COMPAT Compatibility mode trap - 

SIGFPE SS$_DECOVF Decimal overflow trap FPE_DECOVF_TRAP 
SIGFPE SS$_FLTDIV Floating/decimal division by 0 FPE_FLTDIV_TRAP 
SIGFPE SS$_FLTDIV_F Floating divide by 0 fault FPE_FLTDIV_FAULT 
SIGFPE SS$_FLTOVF Floating overflow trap FPE_FLTOVF_TRAP 
SIGFPE SS$_FLTOVF_F Floating overflow fault FPE_FLTOVF_FAULT 
SIGFPE SS$_FLTUND Floating undeflow trap FPE_FLTUND_TRAP 
SIGFPE SS$_FLTUND_F Floating undeflow fault FPE_FLTUND_FAULT 
SIGFPE SS$_INTDIV Integer division by 0 FPE_INTDIV_TRAP 
SIGFPE SS$_INTOVF Integer overflow FPE_INTOVF_TRAP 
SIGFPE SS$_SUBRNG Subscript-range FPE_SUBRNG_TRAP 
SIGHUP SS$_HANGUP Data set hangup = 

SIGILL SS$_OPCDEC Reserved instruction ILL_PRIVIN_FAULT 
SIGILL SS$_RADRMOD Reserved addressing ILL_RESAD_FAULT 
SIGILL SS$_ROPRAND Reserved operand ILL_RESOP_FAULT 
SIGINT SS$_CONTROLC OpenVMS CtrI/C interrupt - 

SIGIOT SS$_OPCCUS Customer-reserved opcode - 

SIGKILL SS$_ABORT External signal only - 

SIGQUIT SS$_CONTROLY The raise function - 

SIGPIPE SS$_NOMBX No mailbox - 

SIGPIPE C$_SIGPIPE Broken pipe - 

SIGSEGV SS$_ACCVIO Length violation - 
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Table 4—4 (Cont.) HP C RTL Signals and Corresponding OpenVMS VAX Exceptions (vax only) 


Name OpenVMS Exception Generated By Code 
SIGSEGV SS$_CMODSUPR Change mode supervisor - 
SIGSYS SS$_BADPARAM Bad argument to system call - 
SIGTERM Not implemented - - 
SIGTRAP SS$_TBIT TBIT trace trap - 
SIGTRAP SS$_BREAK Breakpoint fault instruction - 
SIGUSR1 C$_SIGUSR1 The raise function - 
SIGUSR2 C$_SIGUSR2 The raise function = 
SIGWINCH! C$_SIGWINCH? The raise function = 


1Supported on OpenVMS Version 7.3 and higher. 
28S$ BADWINCNT when C$_SIGWINCH not defined (OpenVMS versions before 7.3). 


To call a signal handler that you have established with signal or sigvec, the 
HP C RTL intercepts the OpenVMS exceptions that correspond to signals by 
having an OpenVMS exception handler in the main routine of the program. If 
your program has a main function, then this exception handler is automatically 
established. If you do not have a main function, or if your main function is written 
in a language other than HP C, then you must invoke the VAXCSCRTL_INIT routine 
to establish this handler. 


The HP C RTL uses OpenVMS exceptions to implement the setjmp and longjmp 
functions. When the longjmp function is called, a C$_LONGJMP OpenVMS 
exception is signaled. To prevent the C$_LONGJMP exception from being 
interfered with by user exception handlers, use the VAXCSESTABLISH routine to 
establish user OpenVMS exception handlers instead of calling LIBS{ESTABLISH. 
The C$ LONGJMP mnemonic is defined in the <errnodef .h> header file. 


If you want to use OpenVMS exception handlers and UNIX signals in your C 
program, your OpenVMS exception handler must be prepared to accept and 
resignal the OpenVMS exceptions listed in Tables 4—4 (vax only) and 4—5 (Alpha only), 
as well as the C$_LONGJMP exception and any C$ facility exception that might 
be introduced in future versions of the HP C RTL. This is because UNIX signals 
are global in context, whereas OpenVMS exceptions are stack-frame based. 


Consequently, an OpenVMS exception handler always receives the exception that 
corresponds to the UNIX signal before the HP C RTL exception handler in the 
main routine does. By resignaling the OpenVMS exception, you allow the HP C 
RTL exception handler to receive the exception. You can intercept any of those 
OpenVMS exceptions yourself, but in doing so you will disable the corresponding 
UNIX signal. 
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Table 4-5 HP C RTL Signals and Corresponding OpenVMS Alpha Exceptions (lpia only) 


Name OpenVMS Exception Generated By Code 

SIGABRT SS$_OPCCUS The abort function — 

SIGALRM SS$_ASTFLT The alarm function - 

SIGBUS SS$_ACCVIO Access violation - 

SIGBUS SS$_CMODUSER Change mode user = 

SIGCHLD C$_SIGCHLD Child process stopped = 

SIGEMT SS$_COMPAT Compatibility mode trap - 

SIGFPE SS$_DECDIV Decimal divide trap FPE_DECDIV_TRAP 
SIGFPE SS$_DECINV Decimal invalid operand trap FPE_DECINV_TRAP 
SIGFPE SS$_DECOVF Decimal overflow trap FPE_DECOVF_TRAP 
SIGFPE SS$_HPARITH Floating/decimal division by 0 FPE_FLTDIV_TRAP 
SIGFPE SS$_HPARITH Floating overflow trap FPE_FLTOVF_TRAP 
SIGFPE SS$_HPARITH Floating undeflow trap FPE_FLTUND_TRAP 
SIGFPE SS$_HPARITH Integer overflow FPE_INTOVF_TRAP 
SIGFPE SS$_HPARITH Invalid operand FPE_INVOPR_TRAP 
SIGFPE SS$_HPARITH Inexact result FPE_INXRES_TRAP 
SIGFPE SS$_INTDIV Integer div by zero FPE_INTDIV_TRAP 
SIGFPE SS$_SUBRNG Subscript out of range FPE_SUBRNG_TRAP 
SIGFPE SS$_SUBRNG1 Subscript1 out of range FPE_SUBRNG1_TRAP 
SIGFPE SS$_SUBRNG2 Subscript2 out of range FPE_SUBRNG2_TRAP 
SIGFPE SS$_SUBRNG3 Subscript3 out of range FPE_SUBRNG3_TRAP 
SIGFPE SS$_SUBRNG4 Subscript4 out of range FPE_SUBRNG4_TRAP 
SIGFPE SS$_SUBRNG5 Subscript5 out of range FPE_SUBRNG5_TRAP 
SIGFPE SS$_SUBRNG6 Subscript6 out of range FPE_SUBRNG6_TRAP 
SIGFPE SS$_SUBRNG7 Subscript7 out of range FPE_SUBRNG7_TRAP 
SIGHUP SS$_HANGUP Data set hangup = 

SIGILL SS$_OPCDEC Reserved instruction ILL_PRIVIN_FAULT 
SIGILL SS$_ROPRAND Reserved operand ILL_RESOP_FAULT 
SIGINT SS$_CONTROLC OpenVMS CtrI/C interrupt - 

SIGIOT SS$_OPCCUS Customer-reserved opcode - 

SIGKILL SS$_ABORT External signal only - 

SIGQUIT SS$_CONTROLY The raise function - 

SIGPIPE SS$_NOMBX No mailbox = 

SIGPIPE C$_SIGPIPE Broken pipe - 

SIGSEGV SS$_ACCVIO Length violation = 

SIGSEGV SS$_CMODSUPR Change mode supervisor - 
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Table 4—5 (Cont.) HP C RTL Signals and Corresponding OpenVMS Alpha Exceptions (ipha only) 


Name OpenVMS Exception Generated By Code 
SIGSYS SS$_BADPARAM Bad argument to system call - 
SIGTERM Not implemented - - 
SIGTRAP SS$_BREAK Breakpoint fault instruction - 
SIGUSR1 C$_SIGUSR1 The raise function - 
SIGUSR2 C$_SIGUSR2 The raise function = 
SIGWINCH! C$ _SIGWINCH? The raise function - 


1Supported on OpenVMS Version 7.3 and higher. 
28S$ BADWINCNT when C$_SIGWINCH not defined (OpenVMS versions before 7.3). 


OpenVMS Alpha Signal-Handling Notes (Alpha only) 


e While all signals that exist on OpenVMS VAX systems also exist on 
OpenVMS Alpha systems, the corresponding OpenVMS exceptions 
and code is different in a number of cases because on Alpha processors 
there are two new OpenVMS exceptions and several others that are 


obsolete. 


e All floating-point exceptions on OpenVMS Alpha systems are signaled 
by the OpenVMS exception SS$_HPARITH (high-performance 
arithmetic trap). The particular type of trap that occurred is 
translated by the HP C RTL through use of the exception summary 
longword, which is set when a high-performance arithmetic trap is 


signaled. 


Table 4-6 HP C RTL Signals and Corresponding OpenVMS 164 Exceptions (764 only) 


Name OpenVMS Exception Generated By Code 

SIGABRT SS$_OPCCUS The abort function - 

SIGALRM SS$_ASTFLT The alarm function - 

SIGBUS SS$_ACCVIO Access violation - 

SIGBUS SS$_CMODUSER Change mode user - 

SIGCHLD C$_SIGCHLD Child process stopped - 

SIGEMT SS$_COMPAT Compatibility mode trap - 

SIGFPE SS$_DECOVF Decimal overflow trap FPE_DECOVF_TRAP 

SIGFPE SS$_DECDIV Decimal divide trap FPE_DECDIV_TRAP 

SIGFPE SS$_DECINV Decimal invalid operand trap FPE_DECINV_TRAP 

SIGFPE SS$_ Denormal operand fault FPE_FLTDENORMAL_ FAULT 
FLTDENORMAL 

SIGFPE SS$_FLTDIV Floating/decimal division by 0 FPE_FLTDIV_TRAP 


(continued on next page) 
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Table 4-6 (Cont.) HP C RTL Signals and Corresponding OpenVMS 164 Exceptions (164 oniy) 


Name OpenVMS Exception Generated By Code 

SIGFPE SS$_FLTDIV_F Floating divide by 0 fault FPE_FLTDIV_FAULT 
SIGFPE SS$_FLTINE Inexact operation trap FPE_FLTINE_TRAP 
SIGFPE SS$_FLTINV Invalid operation trap FPE_FLTINV_TRAP 
SIGFPE SS$_FLTINV_F Invalid operation fault FPE_FLTINV_FAULT 
SIGFPE SS$_FLTOVF Floating overflow trap FPE_FLTOVF_TRAP 
SIGFPE SS$_FLTUND Floating undeflow trap FPE_FLTUND_TRAP 
SIGFPE SS$_INTDIV Integer division by 0 FPE_INTDIV_TRAP 
SIGFPE SS$_INTOVF Integer overflow FPE_INTOVF_TRAP 
SIGFPE SS$_SUBRNG Subscript-range FPE_SUBRNG_TRAP 
SIGHUP SS$_HANGUP Data set hangup = 

SIGILL SS$_OPCDEC Reserved instruction ILL_PRIVIN_FAULT 
SIGILL SS$_ROPRAND Reserved operand ILL_RESOP_FAULT 
SIGINT SS$_CONTROLC OpenVMS CtrI//C interrupt - 

SIGIOT SS$_OPCCUS Customer-reserved opcode - 

SIGKILL SS$_ABORT External signal only - 

SIGQUIT SS$_CONTROLY The raise function - 

SIGPIPE SS$_NOMBX No mailbox = 

SIGPIPE C$_SIGPIPE Broken pipe - 

SIGSEGV SS$_ACCVIO Length violation — 

SIGSEGV SS$_CMODSUPR Change mode supervisor - 

SIGSYS SS$_BADPARAM Bad argument to system call - 

SIGTERM Not implemented - - 

SIGTRAP SS$_TBIT TBIT trace trap - 

SIGTRAP SS$_BREAK Breakpoint fault instruction - 

SIGUSR1 C$_SIGUSR1 The raise function = 

SIGUSR2 C$_SIGUSR2 The raise function = 

SIGWINCH  C$_SIGWINCH The raise function — 


4.3 Program Example 


Example 4—1 shows how the signal, alarm, and pause functions operate. It 
also shows how to establish a signal handler to catch a signal, which prevents 
program termination. 
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Example 4-1 Suspending and Resuming Programs 


/* CHAP 4 SUSPEND RESUME.C */ 


/* This program shows how to alternately suspend and resume a */ 
/* program using the signal, alarm, and pause functions. */ 


#define SECONDS 5 


#include <stdio.h> 
#include <signal.h> 


int number of alarms = 5; /* Set alarm counter. */ 
void alarm_action(int) ; 


main () 

{ 
signal(SIGALRM, alarm action); /* Establish a signal handler. */ 

/* to catch the SIGALRM signal.*/ 


alarm(SECONDS) ; /* Set alarm clock for 5 seconds. */ 
pause () ; /* Suspend the process until * 
* the signal is received. */ 


} 


void alarm_action(int x) 


printf ("\t<%d\007>", number of alarms); /* Print the value of */ 
/* the alarm counter. */ 


signal (SIGALRM, alarm_action) ; /* Reset the signal. */ 

alarm(SECONDS) ; /* Set the alarm clock. */ 

if (--number of alarms) /* Decrement alarm counter. */ 
pause () ; 


} 


Here is the sample output from Example 4-1: 


S$ RUN EXAMPLE 
<5> <4> <3> <2> <l> 
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Subprocess Functions 


The HP C Run-Time Library (RTL) provides functions that allow you to create 
subprocesses from a HP C program. The creating process is called the parent and 
the created subprocess is called the child. 


To create a child process within the parent process, use the exec functions 
(execl, execle, execv, execve, execlp, and execvp) and the vfork function. 
Other functions are available to allow the parent and child to read and write 
data across processes (pipe) and to allow for synchronization of the two processes 
(wait). This chapter describes how to implement and use these functions. 


The parent process can execute HP C programs in its children, either 
synchronously or asynchronously. The number of children that can run 
simultaneously is determined by the /PRCLM user authorization quota 
established for each user on your system. Other quotas that may affect the use of 
subprocesses are /ENQLM (Queue Entry Limit), /ASTLM (AST Waits Limit), and 
/FILLM (Open File Limit). 


This chapter discusses the subprocess functions. Table 5—1 lists and describes all 
the subprocess functions found in the HP C RTL. For more detailed information 
on each function, see the Reference Section. 


Table 5-1 Subprocess Functions 


Function Description 


Implementation of Child Processes 


system Passes a given string to the host environment to be 
executed by a command processor. 


vfork Creates an independent child process. 


The exec Functions 


execl, execle, execlp Passes the name of the image to be activated in a child 
execv, execve, execvp process. 


Synchronizing Process 


wait, wait3, wait4, Suspends the parent process until a value is returned 
waitpid, from a child. 


Interprocess Communication 


pipe Allows for communication between a parent and child. 
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5.1 Implementing Child Processes in HP C 


Child processes are created by HP C functions with the OpenVMS LIB$SPAWN 
RTL routine. (See the VMS Run-Time Library Routines Volume for information 
on LIB$SPAWN.) Using LIB$SPAWN allows you to create multiple levels of child 
processes; the parent’s children can also spawn children, and so on, up to the 
limits allowed by the user authorization quotas discussed in the introduction to 
this chapter. 


Child processes can only execute other HP C programs. Other native-mode 
OpenVMS languages do not share the ability of HP C to communicate between 
processes; if they do, they do not use the same mechanisms. The parent process 
must be run under an HP supported command-language interpreter (CLI), such 
as DCL. You cannot run the parent as a detached process or under control of a 
user-supplied CLI. 


Enabling the DECC$DETACHED_CHILD_PROCESS feature logical allows child 
processes to be created as detached processes instead of subprocesses. This 
feature has only limited support. In some cases, the console cannot be shared 
between the parent process and the detached process, which can cause exec to 
fail. 


Parent and child processes communicate through a mailbox as shown in 

Figure 5-1. This mailbox transfers the context in which the child will run. This 
context mailbox passes information to the child that it inherits from the parent, 
such as the names and file descriptors of all the files opened by the parent and 
the current location within those files. The mailbox is deleted by the parent when 
the child image exits. 


Figure 5-1 Communications Links Between Parent and Child Processes 


context context 


Parent Mailbox 
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Note 


The mailbox created by the vfork and exec functions is temporary. The 
logical name of this mailbox is VAXC$EXECMBxX and is reserved for use 
by the HP C RTL. 


The mailbox is created with a maximum message size and a buffer quota of 
512 bytes each, unless the buffer size and quota are explicitly specified with the 
DECC$PIPE_BUFFER_SIZE or DECC$PIPE_BUFFER_QUOTA feature logicals, 
or with the bufsize or bufquota parameters of the pipe function. See the pipe 
function for more information. 


You need the TMPMBX privilege to create a mailbox with these RTL functions. 
Since TMPMBxX is the privilege required by the DCL commands PRINT and 
SUBMIT, most users on a system have this privilege. To see what system 
privileges you have, enter a SHOW PROCESS/PRIVILEGES command. 
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You cannot change the characteristics of these mailboxes. For more information 
on mailboxes, see the VMS I/O User’s Reference Volume. 


5.2 The exec Functions 


There are six exec functions that you can call to execute an HP C image in the 
child process. These functions expect that vfork has been called to set up a 
return address. The exec functions will call vfork if the parent process did not. 


When vfork is called by the parent, the exec function returns to the parent 
process. When vfork was called by an exec function, the exec function returns 
to itself, waits for the child to exit, and then exits the parent process. The exec 
function does not return to the parent process unless the parent calls vfork to 
save the return address. 


In OpenVMS Version 7.2, the exec functions were enhanced to activate either 
executable images or DCL command procedures. If no file extension is specified 
in the file_name argument, the functions first search for the file with the .EXE 
file extension and then for the file with the .COM file extension. If both the 
executable image and the command procedure with the same name exist, you 
must explicitly specify the .COM file extension to force activating the command 
procedure. 


For a DCL command procedure, the exec functions pass the first eight arg0, arg1, 
.., arguments specified in the exec call to the command procedure as P1, P2, ... 
parameters, preserving the case. 


Unlike UNIX based systems, the exec functions in the HP C RTL cannot always 
determine if the specified executable image or command procedure exists and can 
be activated and executed. Therefore, the exec functions might appear to succeed 
even though the specified file cannot be executed by the child process. 


The status of the child process, returned to the parent process, indicates that the 
error occurred. You can retrieve this error code by using one of the functions from 
the wait family of functions. 


Note 


The vfork and exec functions in the HP C RTL on OpenVMS systems 
work differently than on UNIX systems: 


e On UNIX systems, vfork creates a child process, suspends the parent, 
and starts the child running where the parent left off. 


e On OpenVMS systems, vfork establishes context later used by an 
exec function, but it is the exec function, not vfork, that starts a 
process running the specified program. 


For a progammer, the key differences are: 


e On OpenVMS systems, code between the call to vfork and the call to 
an exec function runs in the parent process. 


On UNIX systems, this code runs in the child process. 


e On OpenVMS systems, the child inherits open file descriptors and so 
on, at the point where the exec function is called. 


On UNIX systems, this occurs at the point where vfork is called. 
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5.2.1 exec Processing 


The exec functions use the LIB$SPAWN routine to create the subprocess and 
activate the child image within the subprocess. This child process inherits the 
parent’s environment, including all defined logical names and command-line 
interpreter symbols. 


By default, child processes also inherit the default (working) directory of their 
parent process. However, you can use the decc$set_ child default dir function 
to set the default directory for a child process as it begins execution. For more 
information about the decc$set_child_default_dir function, see the Reference 
Section. 


The exec functions use the logical name VAXC$EXECMBX to communicate 
between parent and child; this logical name must not exist outside the context of 
the parent image. 


The exec functions pass the following information to the child: 


e The parent’s umask value, which specifies whether any access is to be 
disallowed when a new file is created. For more information about the 
umask function, see the Reference Section. 


e The file-name string associated with each file descriptor and the current 
position within each file. The child opens the file and calls 1seek to position 
the file to the same location as the parent. If the file is a record file, the child 
is positioned on a record boundary, regardless of the parent’s position within 
the record. For more information about file descriptors, see Chapter 2. For 
more information on the lseek function, see the Reference Section. 


This information is sent to the child for all descriptors known to the parent 
including all descriptors for open files, null descriptors, and duplicate 
descriptors. 


File pointers are not transferred to the child. For files opened by a file pointer 
in the parent, only their corresponding file descriptors are passed to the child. 
The fdopen function must be called to associate a file pointer with the file 
descriptor if the child will access the file-by-file pointer. For more information 
about the fdopen function, see the Reference Section. 


The DECC$EXEC_FILEATTR_INHERITANCE feature logical can be used 
to control whether or not a child process inherits file positioning, and if so, 
for which access modes. For more information on DECC$EXEC_FILEATTR_ 
INHERITANCE, see Section 1.6. 


e The signal database. Only SIG_IGN (ignore) actions are inherited. Actions 
specified as routines are changed to SIG_DFL (default) because the parent’s 
signal-handling routines are inaccessible to the child. 


e The environment and argument vectors. 


When everything is transmitted to the child, exec processing is complete. Control 
in the parent process then returns to the address saved by vfork and the child’s 
process ID is returned to the parent. 


See Section 4.2.4 for a discussion of signal actions and the SIGCHLD signal. 
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5.2.2 exec Error Conditions 


The exec functions will fail if LIB$SPAWN cannot create the subprocess. 
Conditions that can cause a failure include exceeding the subprocess quota 

or finding the communications by the context mailbox between the parent and 
child to be broken. Exceeding some quotas will not cause LIB$SPAWN to fail, but 
will put LIB$SPAWN into a wait state that can cause the parent process to hang. 
An example of such a quota is the Open File Limit quota. 


You will need an Open File Limit quota of at least 20 files, with an average of 
three times the number of concurrent processes that your program will run. If 
you use more than one open pipe at a time, or perform I/O on several files at one 
time, this quota may need to be even higher. See your system manager if this 
quota needs to be increased. 


When an exec function fails, a value of —1 is returned. After such a failure, the 
parent is expected to call either the exit or exit function. Both functions then 
return to the parent’s vfork call, which returns the child’s process ID. In this 
case, the child process ID returned by the exec function is less than zero. For 
more information about the exit function, see the Reference Section. 


5.3 Synchronizing Processes 


A child process is terminated when the parent process terminates. Therefore, the 
parent process must check the status of its child processes before exiting. This is 
done using the HP C RTL function wait. 


5.4 Interprocess Communication 


A channel through which parent and child processes communicate is called a 
pipe. Use the pipe function to create a pipe. 


5.5 Program Examples 


Example 5-1 shows the basic procedures for executing an image in a child 
process. The child process in Example 5-1 prints a message 10 times. 


Example 5-1 Creating the Child Process 
/* chap_5 exec _image.c */ 


/* This example creates the child process. The only */ 
/* functionality given to the child is the ability to */ 
/* print a message 10 times. */ 


include <climsgdef.h> /* CLI status values */ 
#include <stdio.h> 

#include <perror.h> 

include <processes.h> 

include <stdlib.h> 


static const char *child name = "chap 5 exec_image child.exe" ; 


ain() 


int status, 
cstatus; 


(continued on next page) 
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Example 5-1 (Cont.) Creating the Child Process 


/* NOTE: */ 
/* Any local automatic variables, even those */ 
/* having the volatile attribute, may have */ 
/* indeterminant values if they are modified */ 
/* between the vfork() call and the matching */ 
/* exec() call. */ 
1 if ((status = vfork()) != 0) 
/* This is either an error or */ 
/* the "second" vfork return, taking us "back" */ 
/* to parent mode. */ 
3 if (status < 0) 
printf("Parent - Child process failed\n") ; 
else { 
printf("Parent - Waiting for Child\n"); 
4 if ((status = wait(&cstatus)) == -1) 
perror("Parent - Wait failed"); 
5 else if (cstatus == CLIS IMAGEFNF) 
printf ("Parent - Child does not exist\n"); 
else 


printf ("Parent - Child final status: %d\n", cstatus) ; 


} 


2 else { /* The FIRST Vfork return is zero, do the exec */ 
printf("Parent - Starting Child\n"); 
if ((status = execl(child name, 0)) == -1) { 


perror("Parent - Execl failed"); 
exit (EXIT_FAILURE) ; 


/* CHAP 5 EXEC IMAGE CHILD.C */ 


/* This is the child program that writes a message */ 
/* through the parent to "stdout" */ 


#include <stdio.h> 


main () 


int 1; 
for (i = 0; 1 < 10; i++) 
printf ("Child - executing\n") ; 
return (255) ; /* Set an unusual success stat */ 


Key to Example 5-1: 


1 The vfork function is called to set up the return address for the exec call. 


The vfork function is normally used in the expression of an if statement. 
This construct allows you to take advantage of the double return aspect of 
vfork, since one return value is 0 and the other is nonzero. 


2 AO return value is returned the first time vfork is called and the parent 
executes the else clause associated with the vfork call, which calls execl. 


3 A negative child process ID is returned when an exec function fails. The 
return value is checked for these conditions. 


5-6 Subprocess Functions 


The wait function is used to synchronize the parent and child processes. 


Since the exec functions can indicate success up to this point even if the 
image to be activated in the child does not exist, the parent checks the child’s 
return status for the predefined status, CLI$_IMAGEFNF (file not found). 


In Example 5-2, the parent passes arguments to the child process. 


Example 5-2 Passing Arguments to the Child Process 


/* 


/* 
/* 
/* 
/* 


CHAP _5 CHILDARG.C */ 
In this example, the arguments are placed in an array, gargv, */ 
but they can be passed to the child explicitly as a zero- */ 


terminated series of character strings. The child program in this */ 
example writes the arguments that have been passed it to stdout. */ 


#include <climsgdef .h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <perror.h> 
#include <processes.h> 


const char *child_name = "chap _5 childarg child.exe" ; 


main () 


{ 


int status, 
cestatus; 
char *gargv[] = 
{"Child", "ARGC1", "ARGC2", "Parent", Oo}; 


if ((status = vfork()) != 0) { 
if (status < -1) 
printf("Parent - Child process failed\n") ; 


else { 
printf("Parent - waiting for Child\n"); 
if ((status = wait(&cstatus)) == -1) 


perror ("Parent - Wait failed"); 
else if (cstatus == CLI$ IMAGEFNF) 
printf ("Parent - Child does not exist\n"); 


else 
printf("Parent - Child final status: %x\n", 
cstatus) ; 

} 
} 
else { 

printf ("Parent - Starting Child\n"); 

if ((status = execv(child name, gargv)) == -1) { 


perror("Parent - Exec failed"); 
exit (EXIT_FAILURE) ; 


CHAP 5 CHILDARG CHILD.C */ 


/* This is a child program that echos its arguments */ 


#include <stdio.h> 


(continued on next page) 
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Example 5-2 (Cont.) Passing Arguments to the Child Process 


mMain(argc, argv) 
int argc; 
char *argv[]; 
int i; 
printf ("Program name: %s\n", argv[0]); 
for (1 = 1; i < argc; i++) 
printf ("Argument %d: %s\n", i, argv[i]); 
return(255) ; 


} 


Example 5—3 shows how to use the wait function to check the final status of 
multiple children being run simultaneously. 


Example 5-3 Checking the Status of Child Processes 


/* CHAP _5 CHECK STAT.C */ 
/* In this example 5 child processes are started. The wait () */ 
/* function is placed in a separate for loop so that it is */ 
/* called once for each child. If wait() were called within */ 
/* the first for loop, the parent would wait for one child to */ 
/* terminate before executing the next child. If there were */ 
/* only one wait request, any child still running when the */ 
/* parent exits would terminate prematurely. */ 


#include <climsgdef.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <perror.h> 
#include <processes.h> 


const char *child_ name = "chap _5 check _stat_child.exe" ; 


aa 
int status, 
estatus, 
ij 
for (i = 0; 1 < 5; i++) { 
if ((status = vfork()) == 0) { 
printf ("Parent - Starting Child %d\n", i); 
if ((status = execl(child name, 0)) == -1) { 
perror("Parent - Exec failed"); 
exit (EXIT_FAILURE) . 


else if (status < -1) 
printf("Parent - Child process failed\n") ; 


} 


printf ("Parent - Waiting for children\n") ; 


(continued on next page) 
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Example 5-3 (Cont.) Checking the Status of Child Processes 


for 


(1 = 0; 1 < 5; i++) { 


if ((status = wait(&cstatus)) == -1) 


perror("Parent - Wait failed"); 


else if (cstatus == CLI$ IMAGEFNF) 


printf ("Parent - Child does not exist\n"); 


else 


} 


printf ("Parent - Child %X final status: %d\n", 


status, cstatus) ; 


Example 5—4 shows how to use the pipe and dup2 functions to communicate 

between a parent and child process through specific file descriptors. The #define 
preprocessor directive defines the preprocessor constants inpipe and outpipe as 
the names of file descriptors 11 and 12. 


Example 5-4 Communicating Through a Pipe 


/* 


CHAP 5 PIPE.C 


/* In this example, the parent writes a string to the pipe for */ 


/* the child to read. 
/* to the pipe for the parent to read. 


The child then writes the string back */ 
The wait function is */ 


/* called before the parent reads the string that the child has */ 


/* passed back through the pipe. 


/* write 


#include 
#include 
include 
include 
#include 
#include 
include 


#define 
define 


main () 


int 
int 


s will not be synchronized. 


<perror.h> 
<climsgdef .h> 
<stdio.h> 
<stdlib.h> 
<string.h> 
<processes.h> 
<unixio.h> 


inpipe 11 
outpipe 12 


const char *child_name = "chap 5 pipe child.exe" ; 


pipes [2]; 
mode, 
status, 
cstatus, 
len; 


char *outbuf, 


if ( 


*inbuf; 


(outbuf = malloc(512)) == 0) 
printf ("Parent - Outbuf allocation failed\n") ; 
exit (EXIT FAILURE) ; 


Otherwise, the reads and */ 


(continued on next page) 
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Example 5-4 (Cont.) Communicating Through a Pipe 


if ((inbuf = malloc(512)) == 0) 
printf ("Parent - Inbuf allocation failed\n") ; 
exit (EXIT_FAILURE ' 


if (pipe(pipes) == -1 
printf("Parent - Pipe allocation failed\n") ; 
exit (EXIT_FAILURE) ; 


dup2(pipes[0], inpipe); 
dup2(pipes[1], outpipe) ; 
strepy(outbuf, "This is a test of two-way pipes.\n"); 


status = vfork(); 


switch (status) { 
case 0: 
printf ("Parent - Starting child\n" 
if ((status = execl(child_name, 0) 
printf ("Parent - Exec failed"); 
exit (EXIT_FAILURE) ; 


iT] 
iT] 
1 
bh 
—— 


break; 


case -1: 
printf ("Parent - Child process failed\n") ; 
break; 


default: 
printf ("Parent - Writing to child\n"); 


if (write(outpipe, outbuf, strlen(outbuf) + 1) == -1) { 
perror("Parent - Write failed") ; 
exit (EXIT_FAILURE) ; 


} 


else 


if ((status = wait(&cstatus)) == -1) 
perror("Parent - Wait failed"); 


if (cstatus == CLI$ IMACEFNF) 
printf("Parent - Child does not exist\n"); 
else { 
printf("Parent - Reading from child\n"); 
if ((len = read(inpipe, inbuf, 512)) <= 0) { 
perror("Parent - Read failed"); 
exit (EXIT FAILURE) ; 


else { 
printf ("Parent: %s\n", inbuf) ; 
printf("Parent - Child final status: %d\n", 


cstatus) ; 
} 
} 
} 
break; 
} 
/* CHAP 5 PIPE CHILD.C */ 


/* This is a child program which reads from a pipe and writes */ 
/* the received message back to its parent. */ 


(continued on next page) 
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Example 5-4 (Cont.) Communicating Through a Pipe 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <unistd.h> 


#define inpipe 11 
#define outpipe 12 


main () 


{ 


char *buffer; 
int len; 


if ((buffer = malloc(512)) == 0) { 
perror("Child - Buffer allocation failed\n") ; 
exit (EXIT FAILURE) ; 


printf ("Child - Reading from parent\n") ; 

if ((len = read(inpipe, buffer, 512)) <= 0) { 
perror ("Child - Read failed") ; 
exit (EXIT_FAILURE) ; 


else { 
printf ("Child: %s\n", buffer) ; 
printf ("Child - Writing to parent\n") ; 


if (write(outpipe, buffer, strlen(buffer) + 1) == -1) { 


perror ("Child - Write failed"); 
exit (EXIT_FAILURE) ; 


exit (EXIT SUCCESS) ; 
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Curses Screen Management Functions and 
Macros 


This chapter describes the screen management routines available with HP C for 
OpenVMS Systems. 


The OpenVMS Curses screen management package is supported on all OpenVMS 
systems. 


On OpenVMS Alpha systems, two screen management packages are supported: 
OpenVMS Curses and a more UNIX compatible package based on the Berkeley 
Standard Distribution (BSD) Curses software.! See Section 6.1 for more 
information. 


Furthermore, the HP C RTL offers a Curses package based on the 4.4BSD 
Berkeley Software Distribution. Documentation on the 4.4BSD Curses package 
can be found in Screen Updating and Cursor Movement Optimization: A Library 
Package, by Kenneth C.R.C. Arnold. 


The functions and macros in the OpenVMS and BSD-based Curses packages are 
nearly the same. Most differences between them are called out in this chapter. 
Otherwise, this chapter makes no distinction between the two Curses packages, 
and refers to "Curses" or the "Curses functions and macros." 


6.1 Using the BSD-Based Curses Package spia ony) 


The <curses.h> header file required to use the BSD-based Curses implementation 
is provided with the HP C compiler on OpenVMS Alpha systems. 


Existing programs are not affected by the BSD-based Curses functions because 
the OpenVMS Curses functions are still available as the default Curses package. 
(Note that is a change from previous versions of HP C, where BSD-based Curses 
was the default.) 


To get the 4.4BSD Curses implementation, you must compile modules that 
include <curses.h> with the following qualifier: 


/DEFINE=_BSD44_CURSES 


The BSD-based Curses functions do not provide the support required to call the 
OpenVMS SMG$ routines with the pasteboard and keyboard allocated by the 
Curses functions. Consequently, Curses programs that rely on calling SMG$ 
entry points, as well as Curses functions, must continue to use the OpenVMS 
Curses implementation. 


Copyright (c) 1981 Regents of the University of California. 
All rights reserved. 
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The BSD-based Curses implementation is not interoperable with the old 
implementation. Attempts to mix calls to the new functions and the old functions 
will result in incorrect output displayed on the screen and could result in an 
exception from an SMG$ routine. 


6.2 Curses Overview 


Curses, the HP C Screen Management Package, is composed of HP C RTL 
functions and macros that create and modify defined sections of the terminal 
screen and optimize cursor movement. Using the screen management package, 
you can develop a user interface that is both visually attractive and user- 
friendly. Curses is terminal-independent and provides simplified terminal screen 
formatting and efficient cursor movement. 


Most Curses functions and macros are listed in pairs where the first routine is a 
macro and the second is a function beginning with the prefix “w,” for “window.” 
These prefixes are delimited by brackets ([ ]). For example, [w] addstr designates 
the addstr macro and the waddstr function. The macros default to the window 
stdscr; the functions accept a specified window as an argument. 


To access the Curses functions and macros, include the <curses.h> header file. 


The terminal-independent Screen Management Software, which is part of the 
OpenVMS RTL, is used to implement Curses. For portability purposes, most 
functions and macros are designed to perform in a manner similar to other C 
implementations. However, the Curses routines depend on the OpenVMS system 
and its Screen Management Software, so performance of some functions and 
macros could differ slightly from those of other implementations. 


Some functions and macros available on other systems are not available with the 
HP C RTL Curses package. 


Some functions, such as [w] clrattr, [w]insstr, mv[w]insstr, and [w]setattr 
are specific to HP C for OpenVMS Systems and are not portable. 


Table 6—1 lists all of the Curses functions and macros found in the HP C RTL. 
For more detailed information on each function and macro, see the Reference 
Section. 


Table 6-1 Curses Functions and Macros 


Function or Macro Description 

[w] addch Adds a character to the window at the current position of the 
cursor. 

[w] addstr Adds a string to the window at the current position of the 
cursor. 

box Draws a box around the window. 

[w] clear Erases the contents of the specified window and resets the 
cursor to coordinates (0,0). 

clearok Sets the clear flag for the window. 

[w] clrattr Deactivates the video display attribute within the window. 

[w] clrtobot Erases the contents of the window from the current position of 


the cursor to the bottom of the window. 


(continued on next page) 
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Table 6-1 (Cont.) Curses Functions and Macros 


Function or Macro 


Description 


[w] clrtoeol 


[no] crmode 
[w] delch 


[w] deleteln 
delwin 


[no] echo 
endwin 


[w] erase 
[w] getch 


[w] getstr 
getyx 
[w] inch 


initscr 
[w] insch 


[w] insertln 
[w] insstr 
leaveok 


longname 


[w] move 

mv [w] addch 
mv [w] addstr 
mvcur 

mv [w] delch 


mv [w] getch 


mv [w] getstr 


mv [w] inch 


Erases the contents of the window from the current cursor 
position to the end of the line on the specified window. 


Sets and unsets the terminal from cbreak mode. 


Deletes the character on the specified window at the current 
position of the cursor. 


Deletes the line at the current position of the cursor. 
Deletes the specified window from memory. 


Sets the terminal so that characters may or may not be echoed 
on the terminal screen. 


Clears the terminal screen and frees any virtual memory 
allocated to Curses data structures. 


Erases the window by painting it with blanks. 


Gets a character from the terminal screen and echoes it on the 
specified window. 


Gets a string from the terminal screen, stores it in a character 
variable, and echoes it on the specified window. 


Puts the (y,x) coordinates of the current cursor position on the 
window in the variables y and x. 


Returns the character at the current cursor position on the 
specified window without making changes to the window. 


Initializes the terminal-type data and all screen functions. 


Inserts a character at the current cursor position in the 
specified window. 


Inserts a line above the line containing the current cursor 
position. 


Inserts a string at the current cursor position on the specified 
window. 


Leaves the cursor at the current coordinates after an update to 
the window. 


Assigns the full terminal name to a character name that must 
be large enough to hold the character string. 


Changes the current cursor position on the specified window. 
Moves the cursor and adds a character to the specified window. 
Moves the cursor and adds a string to the specified window. 
Moves the terminal’s cursor. 


Moves the cursor and deletes a character on the specified 
window. 


Moves the cursor, gets a character from the terminal screen, 
and echoes it on the specified window. 


Moves the cursor, gets a string from the terminal screen, stores 
it in a variable, and echoes it on the specified window. 


Moves the cursor and returns the character on the specified 
window without making changes to the window. 


(continued on next page) 
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Table 6-1 (Cont.) Curses Functions and Macros 


Function or Macro 


Description 


mv [w] insch 


mv [w] insstr 


mvwin 
newwin 
[no] nl 


overlay 


overwrite 


[w] printw 
[no] raw 


[w] refresh 


[w] scanw 
scroll 
scrollok 
[w] setattr 
[w] standend 
[w] standout 
subwin 


touchwin 


wrapok 


Moves the cursor and inserts a character in the specified 
window. 


Moves the cursor and inserts a string in the specified window. 


Moves the starting position of the window to the specified 
coordinates. 


Creates a new window with lines and columns starting at the 
coordinates on the terminal screen. 


Provided only for UNIX software compatibility and has no 
functionality in the OpenVMS environment. 


Writes the contents of one window that will fit over the 
contents of another window, beginning at the starting 
coordinates of both windows. 


Writes the contents of one window, insofar as it will fit, over 
the contents of another window beginning at the starting 
coordinates of both windows. 


Performs a printf on the window starting at the current 
position of the cursor. 


Provided only for UNIX software compatibility and has no 
functionality in the OpenVMS environment. 


Repaints the specified window on the terminal screen. 
Performs a scanf on the window. 

Moves all the lines on the window up one line. 

Sets the scroll flag for the specified window. 

Activates the video display attribute within the window. 
Deactivates the boldface attribute for the specified window. 
Activates the boldface attribute of the specified window. 


Creates a new subwindow with lines and columns starting at 
the coordinates on the terminal screen. 


Places the most recently edited version of the specified window 
on the terminal screen. 


OpenVMS Curses only. Allows the wrapping of a word from 
the right border of the window to the beginning of the next 
line. 


6.3 Curses Terminology 


This section explains some of the Curses terminology and shows you how Curses 
looks on the terminal screen. 


Consider a Curses application as being a series of overlapping windows. Window 
overlapping is called occlusion. To distinguish the boundaries of these occluding 
windows, you can outline the rectangular windows with specified characters, or 
you can turn on the reverse video option (make the window a light background 


with dark writing). 
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6.3.1 Predefined Windows (stdscr and curscr) 


Initially, two windows the size of the terminal screen are predefined by Curses. 
These windows are called stdscr and curscr. The stdscr window is defined for 
your use. Many Curses macros default to this window. For example, if you draw 
a box around stdscr, move the cursor to the left-corner area of the screen, write 
a string to stdscr, and then display stdscr on the terminal screen, your display 
will look like that in Figure 6-1. 


Figure 6-1 An Example of the stdscr Window 


Welcome to Curses _ 


ZK-5752-GE 


The second predefined window, curscr, is designed for internal Curses work; 

it is an image of what is currently displayed on the terminal screen. The only 
HP C for OpenVMS Curses function that will accept this window as an argument 
is clearok. Do not write to or read from curscr. Use stdscr and user-defined 
windows for all your Curses applications. 


6.3.2 User-Defined Windows 


You can occlude stdscr with your own windows. The size and location of each 
window is given in terms of the number of lines, the number of columns, and the 
starting position. 


The lines and columns of the terminal screen form a coordinate system, or grid, 
on which the windows are formed. You specify the starting position of a window 
with the (y,x) coordinates on the terminal screen where the upper left corner of 
the window is located. The coordinates (0,0) on the terminal screen, for example, 
are the upper left corner of the screen. 


The entire area of the window must be within the terminal screen borders; 
windows can be as small as a single character or as large as the entire terminal 
screen. You can create as many windows as memory allows. 
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When writing to or deleting from windows, changes do not appear on the terminal 
screen until the window is refreshed. When refreshing a window, you place the 
updated window onto the terminal screen, which leaves the rest of the screen 
unaltered. 


All user-defined windows, by default, occlude stdscr. You can create two or more 
windows that occlude each other as well as stdscr. When writing data to one 
occluding window, the data is not written to the underlying window. 


You can create overlapping windows (called swbwindows). A declared window 
must contain the entire area of its subwindow. When writing data to a 
subwindow or to the portion of the window overlapped by the subwindow, both 
windows contain the new data. For instance, if you write data to a subwindow 
and then delete that subwindow, the data is still present on the underlying 
window. 


If you create a window that occludes stdscr and a subwindow of stdscr, your 
terminal screen will look like Figure 6-2. 


Figure 6—2 Displaying Windows and Subwindows 


ZK-5754-GE 


If you delete both the user-defined window and the subwindow, and then update 
the terminal screen with the new image, your terminal screen will look like 
Figure 6-3. 
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Figure 6—3 Updating the Terminal Screen 
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The string written on the window is deleted, but the string written on the 
subwindow remains on stdscr. 


6.4 Getting Started with Curses 


There are commands that you must use to initialize and restore the terminal 
screen when using Curses Screen Management functions and macros. Also, there 
are predefined variables and constants on which Curses depends. Example 6—1 
shows how to set up a program using Curses. 


Example 6-1 A Curses Program 


1 #include <curses.h> 
2 WINDOW *winl, *win2, *win3; 


main () 


3 initscr(); 


envi G3 


Key to Example 6-1: 


1 The preprocessor directive includes the <curses.h> header file, which defines 
the data structures and variables used to implement Curses. The <curses.h> 
header file includes the <stdio.h> header file, so it is not necessary to 
duplicate this action by including <stdio.h> again in the program source 
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code. You must include <curses.h> to use any of the Curses functions or 
macros. 


2 In the example, WINDOW is a data structure defined in <curses.h>. You 
must declare each user-specified window in this manner. In Example 6-1, the 
three defined windows are winl, win2, and win3. 


3 The initscr and endwin functions begin and end the window editing session. 
The initscr function clears the terminal screen (for OpenVMS Curses only; 
BSD-based Curses does not clear the screen), and allocates space for the 
windows stdscr and curscr. The endwin function deletes all windows and 
clears the terminal screen. 


Most Curses users wish to define and modify windows. Example 6—2 shows you 
how to define and write to a single window. 


Example 6-2 Manipulating Windows 


#include <curses.h> 
WINDOW *winl, *win2, *win3; 


main () 


{ 


initser(); 


_ 


winl = newwin(24, 80, 0, 0); 
2 mvwaddstr(winl, 2, 2, "HELLO"); 


endwin(); 


} 


Key to Example 6-2: 


1 The newwin function defines a window 24 rows high and 80 columns wide with 
a starting position at coordinates (0,0), the upper left corner of the terminal 
screen. The program assigns these attributes to winl. The coordinates are 
specified as follows: (lines,columns) or (y,x). 


2 The mvwaddstr macro performs the same task as a call to the separate macros 
move and addstr. The mvwaddstr macro moves the cursor to the specified 
coordinates and writes a string onto stdscr. 


Note 


Most Curses macros update stdscr by default. Curses functions that 
update other windows have the same name as the macros but with the 
added prefix “w”. For example, the addstr macro adds a given string to 
stdscr at the current cursor position. The waddstr function adds a given 
string to a specified window at the current cursor position. 


When updating a window, specify the cursor position relative to the origin of the 
window, not the origin of the terminal screen. For example, if a window has a 
starting position of (10,10) and you want to add a character to the window at its 
starting position, specify the coordinates (0,0), not (10,10). 
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The string HELLO in Example 6—2 does not appear on the terminal screen until 
you refresh the screen. You accomplish this by using the wrefresh function. 
Example 6—3 shows how to display the contents of winl on the terminal screen. 


Example 6-3 Refreshing the Terminal Screen 


#include <curses.h> 
WINDOW *winl, *win2, *win3; 


main () 


initscr(); 


winl = newwin(22, 60, 0, 0); 
mvwaddstr(winl, 2, 2, "HELLO"); 
wrefresh(win1) ; 


endwin(); 


} 


The wrefresh function updates just the region of the specified window on the 
terminal screen. When the program is executed, the string HELLO appears 

on the terminal screen until the program executes the endwin function. The 
wrefresh function only refreshes the part of the window on the terminal screen 
that is not overlapped by another window. If winl was overlapped by another 
window and you want all of winl to be displayed on the terminal screen, call the 
touchwin function. 


6.5 Predefined Variables and Constants 


The <curses.h> header file defines variables and constants useful for 
implementing Curses (see Table 6—2). 


Table 6-2 Curses Predefined Variables and #define Constants 


Name Type Description 

curscr WINDOW * Window of current screen 

stdser WINDOW * Default window 

LINES int Number of lines on the terminal screen 
COLS int Number of columns on the terminal screen 
ERR — Flag (0) for failed routines 

OK — Flag (1) for successful routines 

TRUE — Boolean true flag (1) 

FALSE — Boolean false flag (0) 

_BLINK — Parameter for setattr and clrattr 
_BOLD —_ Parameter for setattr and clrattr 


(continued on next page) 
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Table 6-2 (Cont.) Curses Predefined Variables and #define Constants 


Name Type Description 
_REVERSE — Parameter for setattr and clrattr 
_UNDERLINE — Parameter for setattr and clrattr 


For example, you can use the predefined macro ERR to test the success or failure 
of a Curses function. Example 6—4 shows how to perform such a test. 


Example 6-4 Curses Predefined Variables 


#include <curses.h> 
WINDOW *winl, *win2, *win3; 
main () 


initser(); 
winl = newwin(10, 10, 1, 5); 


if (mvwin(winl, 1, 10) == ERR) 
addstr("The MVWIN function failed."); 


endwin(); 


} 


In Example 6-4, if the mvwin function fails, the program adds a string to stdscr 
that explains the outcome. The Curses mvwin function moves the starting position 
of a window. 


6.6 Cursor Movement 


In the UNIX system environment, you can use Curses functions to move the 
cursor across the terminal screen. With other implementations, you can either 
allow Curses to move the cursor using the move function, or you can specify the 
origin and the destination of the cursor to the mvcur function, which moves the 
cursor in a more efficient manner. 


In HP C for OpenVMS Systems, the two functions are functionally equivalent and 
move the cursor with the same efficiency. 


Example 6—5 shows how to use the move and mvcur functions. 
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Example 6-5 The Cursor Movement Functions 
#include <curses.h> 


main () 


initscr(); 


clear(); 

move (10, 10); 

move (LINES/2, COLS/2) ; 
mvcur(0, COLS-1, LINES-1, 0); 


khoOND — 


endwin(); 


} 

Key to Example 6-5: 

1 The clear macro erases stdscr and positions the cursor at coordinates (0,0). 
2 The first occurrence of move moves the cursor to coordinates (10,10). 


3 The second occurrence of move uses the predefined variables LINES and 
COLS to calculate the center of the screen (by calculating the value of half 
the number of LINES and COLS on the screen). 


4 The mvcur function forces absolute addressing. This function can address the 
lower left corner of the screen by claiming that the cursor is presently in the 
upper right corner. You can use this method if you are unsure of the current 
position of the cursor, but move works just as well. 


6.7 Program Example 


The following program example shows the effects of many of the Curses macros 
and functions. You can find explanations of the individual lines of code, if not 
self-explanatory, in the comments to the right of the particular line. Detailed 
discussions of the functions follow the source code listing. 


Example 6-6 shows the definition and manipulation of one user-defined window 
and stdscr. 


Example 6-6 stdscr and Occluding Windows 


/* CHAP 6 STDSCR_OCCLUDE.C */ 
/* This program defines one window: winl. winl is */ 
/* located towards the center of the default window */ 


/* stdscr. When writing to an occluding window (winl) */ 
/* that is later erased, the writing is erased as well. */ 


#include <curses.h> /* Include header file. */ 
WINDOW *winl; /* Define windows. */ 
main () 

char str[80]; /* Variable declaration.*/ 


(continued on next page) 
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Example 6-6 (Cont.) stdscr and Occluding Windows 


initscr(); /* Set up Curses. */ 
noecho() ; /* Turn off echo. */ 
/* Create window. */ 


winl = newwin(10, 20, 10, 10); 


box(stdscr, '|’, '-'); /* Draw a box around stdscr. */ 
box(winl, ‘|’, ‘-'); /* Draw a box around winl. */ 
refresh(); /* Display stdscr on screen. */ 
wrefresh(winl) ; /* Display winl on screen. */ 
1 getstr(str); /* Pause. Type a few words! */ 
mvaddstr(22, 1, str); 
2 getch(); 
/* Add string to winl. */ 
mvwaddstr(winl, 5, 5, "Hello"); 
wrefresh (winl) ; /* Add winl to terminal scr. */ 
getch(); /* Pause. Press Return. */ 
delwin (win) ; /* Delete winl. */ 
3 touchwin(stdscr); /* Refresh all of stdscr. */ 
getch(); /* Pause. Press Return. */ 
endwin() ; /* Ends session. */ 


} 


Key to Example 6-6: 


1 The program waits for input. The echo was disabled using the noecho macro, 
so the words that you type do not appear on stdscr. However, the macro 
stores the words in the variable str for use elsewhere in the program. 


2 The getch macro causes the program to pause. When you are finished 
viewing the screen, press Return so the program can resume. The getch 
macro refreshes stdscr on the terminal screen without calling refresh. The 
screen appears like Figure 6-4. 
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Figure 6—4 An Example of the getch Macro 


ZK-5751-GE 


3 The touchwin function refreshes the screen so that all of stdscr is visible and 
the deleted occluding window no longer appears on the screen. 
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Math Functions 


Table 7-1 lists and describes the math functions in the HP C Run-Time Library 
(RTL). For more detailed information on each function, see the Reference 


Section. 


Table 7-1 Math Functions 


Function Description 
abs Returns the absolute value of an integer. 
acos Returns the arc cosine of its radian argument, in the range 


acosd (Alpha, 164) 


acosh (Alpha, 164) 


asin 
asind (Alpha, 164) 


asinh (Alpha, 164) 
atan 


atand (Alpha, 164) 
atan2 
atand2 (Alpha, 164) 


atanh (Alpha, 164) 
cabs 


cbrt (Alpha, 164) 
ceil 


copysign (Alpha, 164) 
cos 

cosd (Alpha, 164) 
cosh 

cot 


[0,7] radians. 


Returns the arc cosine of its radian argument, in the range 
[0,180] degrees. 


Returns the hyperbolic arc cosine of its argument. 


Returns the arc sine of its radian argument in the range 
[—1/2, 7/2] radians. 


Returns the arc sine of its radian argument, in the range 
[—90, 90] degrees. 


Returns the hyperbolic arc sine of its argument. 


Returns the arc tangent of its radian argument, in the range 
[—a/2, 7/2] radians. 


Returns the arc tangent of its radian argument, in the range 
[—90, 90] degrees. 


Returns the arc tangent of y/x (its two radian arguments), in 
the range [—7, 7] radians. 


Returns the arc tangent of y/x (its two radian arguments), in 
the range [—180, 180] degrees. 


Returns the hyperbolic arc tangent of its radian argument. 


Returns the absolute value of a complex number as: 
sqrt (2? + y”). 


Returns the rounded cube root of its argument. 


Returns the smallest integer greater than or equal to its 
argument. 


Returns its first argument with the same sign as its second. 
Returns the cosine of its radian argument in radians. 
Returns the cosine of its radian argument in degrees. 
Returns the hyperbolic cosine of its argument. 

Returns the cotangent of its radian argument in radians. 


(continued on next page) 
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Table 7-1 (Cont.) Math Functions 


Function 


Description 


cotd (Alpha, 164) 


drand48, erand48, 
jrand48, lrand48, 
mrand48, nrand48 


erf (Alpha, 164) 
erfc (Alpha, I64) 
exp 

expml (Alpha, 164) 
fabs 

finite (Alpha, 164) 
floor 

fmod 


fp_class (Alpha, 164) 


ignan (Alpha, 164) 
30, j1, jn (Alpha, 164) 
frexp 


hypot 


initstate 
labs 
lcong48 


lgamma (Alpha, 164) 
llabs, gabs (Alpha, 164) 
ldexp 

ldiv, div 

lldiv, qdiv (Alpha, 164) 


1og2 (Alpha, 164) , log, 
log10 


loglp (Alpha, 164) 


logb (Alpha, 164) 
nextafter (Alpha, 164) 


nint (Alpha, 164) 
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Returns the cotangent of its radian argument in degrees. 


Generates uniformly distributed pseudorandom number 
sequences. Returns 48-bit, nonnegative, double-precision 
floating-point values. 


Returns the error function of its argument. 

Returns (1.0 — erf(x«)). 

Returns the base e raised to the power of the argument. 
Returns exp(x) — 1. 

Returns the absolute value of a floating-point value. 

Returns 1 if its argument is a finite number; 0 if not. 

Returns the largest integer less than or equal to its argument. 


Computes the floating-point remainder of its first argument 
divided by its second. 


Determines the class of IEEE floating-point values, returning a 
constant from the <fp_class.h> header file. 


Test for NaN. Returns 1 if its argument is a NaN; 0 if not. 
Computes Bessel functions of the first kind. 


Calculates the fractional and exponent parts of a floating-point 
value. 


Returns the square root of the sum of the squares of two 
arguments. 


Initializes random number generators. 
Returns the absolute value of an integer as a long int. 


Initializes a 48-bit uniformly distributed pseudorandom 
number sequence. 


Computes the logarithm of the gamma function. 
Returns the absolute value of an __ int 64 integer. 


Returns its first argument multiplied by 2 raised to the power 
of its second argument. 


Returns the quotient and remainder after the division of their 
arguments. 


Returns the quotient and remainder after the division of their 
arguments. 


Returns the logarithm of their arguments. 


Computes In(1+«) accurately. 
Returns the radix-independent exponent of its argument. 


Returns the next machine-representable number following x in 
the direction of y. 


Returns the nearest integral value to the argument. 


(continued on next page) 
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Function Description 


modf Returns the positive fractional part of its first argument 
and assigns the integral part to the object whose address is 
specified by the second argument. 

pow Returns the first argument raised to the power of the second. 

rand, srand Returns pseudorandom numbers in the range 0 to 2°! — 1. 

random, srandom Generates pseudorandom numbers in a more random sequence. 


rint (Alpha, 164) Rounds its argument to an integral value according to the 


scalb (Alpha, 164) 
seed48, srand48 
setstate 

sin 

sind (Alpha, 164) 
sinh 

sqrt 

tan 

tand (Alpha, 164) 
tanh 

trunc (Alpha, 164) 


current IEEE rounding direction specified by the user. 
Returns the exponent of a floating-point number. 
Initializes a 48-bit random number generator. 
Restarts, and changes random number generators. 
Returns the sine of its radian argument in radians. 
Returns the sine of its radian argument in degrees. 
Returns the hyperbolic sine of its argument. 

Returns the square root of its argument. 

Returns the tangent of its radian argument in radians. 
Returns the tangent of its radian argument in degrees. 
Returns the hyperbolic tangent of its argument. 


Truncates its argument to an integral value. 


unordered (Alpha, I64) Returns 1 if either or both of its arguments is a NaN; 0, if not. 


yO, yl, yn Alpha, 164) Computes Bessel functions of the second kind. 


7.1 Math Function Variants—float, long double aire, 12 


Additional math routine variants are supported for HP C on OpenVMS Alpha and 
164 systems only. They are defined in <math.h> and are float and long double 
variants of the routines listed in Table 7-1. 


Float variants take float arguments and return float values. Their names have 
an f suffix. For example: 


float cosf (float x); 
float tandf (float x); 


Long double variants take long double arguments and return long double 
values. Their names have an 1 suffix. For example: 


long double cosl (long double x); 
long double tandl (long double x); 


All math routine variants are included in the Reference Section of this manual. 


Note that for programs compiled without /L_DOUBLE=64 (that is, compiled 
with the default /L_DOUBLE=128), the long double variants of these HP C RTL 
math routines map to the X_FLOAT entry points documented in the HP Portable 
Mathematics Library (HPML) manual. 
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7.2 Error Detection 


To help you detect run-time errors, the <errno.h> header file defines the following 
two symbolic values that are returned by many (but not all) of the mathematical 
functions: 


e EDOM indicates that an argument is inappropriate; the argument is not 
within the function’s domain. 


e ERANGE indicates that a result is out of range; the argument is too large or 
too small to be represented by the machine. 


When using the math functions, you can check the external variable errno for 
either or both of these values and take the appropriate action if an error occurs. 


The following program example checks the variable errno for the value EDOM, 
which indicates that a negative number was specified as input to the function 
sqrt: 

#include <errno.h> 


#include <math.h> 
#include <stdio.h> 


main () 


double input, square root; 


printf("Enter a number: "); 
scanf("Sle", &input) ; 
errno = 0; 
square root = sqrt (input) ; 
if (errno == EDOM) 
perror ("Input was negative") ; 
else 
printf ("Square root of %e = %e\n", 
input, square root) ; 


} 
If you did not check errno for this symbolic value, the sqrt function returns 0 


when a negative number is entered. For more information about the <errno.h> 
header file, see Chapter 4. 


7.3 The <fp.h> Header File 


The <fp.h> header file implements some of the features defined by the Numerical 
C Extensions Group of the ANSI X3J11 committee. You might find this useful for 
applications that make extensive use of floating-point functions. 


Some of the double-precision functions listed in this chapter return the value 
+HUGE_VAL (defined in either <math.h> or <fp.h>) if the result is out of range. 
The float version of those functions return the value HUGE_VALF (defined only 
in <fp.h>) for the same conditions. The long double version returns the value 
HUGE_VALL (also defined in <fp.h>). 


For programs compiled to enable IEEE infinity and NaN values, the values 
HUGE_VAL, HUGE_VALF, and HUGE_VALL are expressions, not compile-time 
constants. Initializations such as the following cause a compile-time error: 
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$ CREATE IEEE INFINITY.C 
#include <fp.h> 


double my_huge_val = HUGE VAL 
“Z 


$ CC /FLOAT=IEEE/IEEE=DENORM IEEE INFINITY 
double my_huge_val = HUGE VAL; 


%CC-E-NEEDCONSTEXPR, In the initializer for my huge val, "decc$gt_dbl infinity" 
is not constant, but occurs in a context that requires a constant expression. 


at line number 3 in file WORK1S: [RTL] IEEE INFINITY.C;1 
$ 


When using both <math.h> and <fp.h>, be aware that <math.h> defines a 
function isnan and <fp.h> defines a macro by the same name. Whichever header 
is included first in the application will resolve a reference to isnan. 


7.4 Example 


Example 7—1 shows how the tan, sin, and cos functions operate. 


Example 7-1 Calculating and Verifying a Tangent Value 


/* CHAP_7 MATH EXAMPLE.C 


/* This example uses two functions --- mytan and main --- 
/* to calculate the tangent value of a number, and to check 


/* the calculation using the sin and cos functions. 


#include <math.h> 
#include <stdio.h> 


/* This function calculates the tangent using the sin and 


/* cogs functions. 
double mytan (x) 
double x; 


double y, 
yl, 
y2; 


yl = sin(x) 
y2 = cos (x) 


if ( 
y = yl / y2; 
return y; 


main () 


double x; 


/* Print values: compare */ 
for (x = 0.0; x < 1.5; x t= 0.1) 


printf ("tan of %4.1£ = %6.2f\t%6.2£\n", x, mytan(x), tan(x)); 
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Example 7—1 produces the following output: 


$ RUN EXAMPLE 


tan of 0.0 = 0.00 0.00 
tan of 0.1 = 0.10 0.10 
tan of 0.2 = 0.20 0.20 
tan of 0.3 = 0.31 0.31 
tan of 0.4 = 0.42 0.42 
tan of 0.5 = 0.55 0.55 
tan of 0.6 = 0.68 0.68 
tan of 0.7 = 0.84 0.84 
tan of 0.8 = 1.03 1.03 
tan of 0.9 = 1.26 1.26 
tan of 1.0 = 1.56 1.56 
tan of 1.1 = 1.96 1.96 
tan of 1.2 = Pop | 2 Duk 
tan of 1.3 = 3.60 3.60 
tan of 1.4 = 5.80 5.80 
$ 
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Memory Allocation Functions 


Table 8—1 lists and describes all the memory allocation functions found in the 
HP C Run-Time Library (RTL). For a more detailed description of each function, 
see the Reference Section. 


Table 8-1 Memory Allocation Functions 


Function Description 

brk, sbrk Determine the lowest virtual address that is not used with the 
program. 

calloc, malloc Allocate an area of memory. 

cfree, free Make available for reallocation the area allocated by a previous 


calloc, malloc, or realloc call. 


realloc Changes the size of the area pointed to by the first argument 
to the number of bytes given by the second argument. 


strdup Duplicates a string. 


All HP C RTL functions requiring additional storage from the heap get 
that storage using the HP C RTL memory allocation functions malloc, 
calloc, realloc, free, and cfree. Memory allocated by these functions is 
quadword-aligned. 


The ANSI C standard does not include cfree. For this reason, it is preferable to 
free memory using the functionally equivalent free function. 


The brk and sbrk functions assume that memory can be allocated contiguously 
from the top of your address space. However, the malloc function and RMS 
may allocate space from this same address space. Do not use the brk and sbrk 
functions in conjunction with RMS and HP C RTL routines that use malloc. 


Previous versions of the VAX C RTL documentation indicated that the memory 
allocation routines used the OpenVMS RTL functions LIB$GET_VM and 
LIB$FREE_VM to acquire and return dynamic memory. This is no longer the 
case; interaction between these routines and the HP C RTL memory allocation 
routines is no longer problematic (although LIB$SHOW_VM can no longer be 
used to track HP C RTL malloc and free usage). 


The HP C RTL memory allocation functions calloc, malloc, realloc, and 
free are based on the LIB$ routines LIB$VM_CALLOC, LIB$VM_MALLOC, 
LIB$VM_REALLOC and LIB$VM_FREE, respectively. 


The routines VAXCSCALLOC_OPT, VAXCSCFREE_ OPT, VAXCSFREE_ OPT, 
VAXCSMALLOC_OPT, and VAXCSREALLOC_OPT are now obsolete and should not 
be used in new development. However, versions of these routines that are 
equivalent to the standard C memory allocation routines are provided for 
backward compatibility. 
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8.1 Program Example 


Example 8—1 shows the use of the malloc, calloc, and free functions. 


Example 8-1 Allocating and Deallocating Memory for Structures 


/* CHAP 8 MEM MANAGEMENT .C */ 


/* This example takes lines of input from the terminal until */ 
/* it encounters a Ctrl/Z, places the strings into an */ 
/* allocated buffer, copies the strings to memory allocated for */ 
/* structures, prints the lines back to the screen, and then */ 
/* deallocates all the memory used for the structures. */ 


#include <stdlib.h> 
#include <stdio.h> 
#define MAX LINE LENGTH 80 


struct line rec { /* Declare the structure. */ 
struct line rec *next; /* Pointer to next line. */ 
char *data; /* DB line from terminal. */ 


int main(void) 


char *buffer; 


/* Define pointers to */ 
/* structure (input lines). */ 


struct line rec *first_line = NULL, 
*next_line, 
*last_line = NULL; 


/* Buffer points to memory. */ 
buffer = malloc(MAX LINE LENGTH) ; 


if (buffer == NULL) { /* If error ... */ 
perror ("malloc") ; 
exit (EXIT FAILURE) ; 


while (gets(buffer) != NULL) { /* While not Ctrl/Z ... */ 
/* Allocate for input line. */ 
next_line = calloc(1, sizeof (struct line _rec)); 


if (next_line == NULL) { 


perror ("calloc") ; 
exit (EXIT_FAILURE F 


/* Put line in data area. */ 
next_line->data = buffer; 
if (last line == NULL) /* Reset pointers. */ 


first_line = next_line; 
else 
last_line->next = next_line; 


last_line = next_line; 

/* Allocate space for the */ 
/* next input line. */ 
buffer = malloc(MAX LINE LENGTH) ; 


(continued on next page) 


8-2 Memory Allocation Functions 


Example 8-1 (Cont.) Allocating and Deallocating Memory for Structures 


if (buffer == NULL) { 
perror ("malloc") ; 
exit (EXIT_FAILURE) ; 


free (buffer) ; /* Last buffer always unused. */ 
next_line = first line; /* Pointer to beginning. */ 


while (next line != NULL) { 
puts(next_line->data); /* Write line to screen. */ 
free(next_line->data); /* Deallocate a line. */ 
last_line = next_line; 
next_line = next_line->next; 
free (last_line) ; 


} 


exit (EXIT_SUCCESS) ; 


} 


The sample input and output for Example 8-1 are as follows: 


$ RUN EXAMPLE 
line one 

line two 

Cz 
EXIT 
line one 
line two 


$ 


Memory Allocation Functions 8-3 


9 


System Functions 


The C programming language is a good choice if you wish to write operating 
systems. For example, much of the UNIX operating system is written in C. When 
writing system programs, it is sometimes necessary to retrieve or modify the 
environment in which the program is running. This chapter describes the HP C 
Run-Time Library (RTL) functions that accomplish this and other system tasks. 


Table 9-1 lists and describes all the system functions found in the HP C RTL. 
For a more detailed description of each function, see the Reference Section. 


Table 9-1 System Functions 


Function 


Description 


System Functions—Searching and Sorting Utilities 


bsearch 


qsort 


Performs a binary search on an array of sorted objects for a 
specified object. 


Sorts an array of objects in place by implementing the quick- 
sort algorithm. 


System Functions—Retrieving Process Information 


ctermid 


cuserid 
getcwd 


getegid, geteuid, 
getgid, getuid 


getenv 
getlogin 


getpid 
getppid 
getpwnam 
getpwuid 


Returns a character string giving the equivalence string 
of SYS$COMMAND, which is the name of the controlling 
terminal. 


Returns a pointer to a character string containing the name of 
the user who initiated the current process. 


Returns a pointer to the file specification for the current 
working directory. 


Return, in OpenVMS terms, group and member numbers from 
the user-identification code (UIC). 


Searches the environment array for the current process and 
returns the value associated with a specified environment. 


Gets the login name of the user associated with the current 
session. 


Returns the process ID of the current process. 
Returns the parent process ID of the calling process. 
Accesses user-name information in the user database. 


Accesses user-ID information in the user database. 


(continued on next page) 
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Function 


Description 


System Functions—Changing Process Information 


chdir 
chmod 
chown 
mkdir 
nice 


putenv 
setenv 


setgid, setuid 
sleep, usleep 


umask 


Changes the default directory. 

Changes the file protection of a file. 

Changes the owner user identification code (UIC) of a file. 
Creates a directory. 


Increases or decreases the process priority to the process base 
priority by the amount of the argument. 


Sets an environmental variable. 


Inserts or resets the environment variable name in the current 
environment list. 


Implemented for program portability and have no functionality. 


Suspend the execution of the current process for at least the 
number of seconds indicated by its argument. 


Creates a file protection mask that is used whenever a new file 
is created. It returns the old mask value. 


System Functions—Retrieving and Converting Date/Time Information 


asctime 
clock 


clock getres 
clock gettime 


clock settime 
ctime 


decc$fix_time 
difftime 
ftime 


getclock 
getdate 
getitimer 
gettimeofday 
gmt ime 
localtime 


mktime 
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Converts a broken-down time into a 26-character string. 


Determines the CPU time, in microseconds, used since the 
beginning of the program execution. 


Gets the resolution for the specified clock. 


Returns the current time (in seconds and nanoseconds) for the 
specified clock. 


Sets the specified clock. 


Converts a time, in seconds, to an ASCII string in the form 
generated by the asctime function. 


Converts OpenVMS binary system times to UNIX binary 
times. 


Computes the difference, in seconds, between the two times 
specified by its arguments. 


Returns the elapsed time since 00:00:00, January 1, 1970, in 
the structure timeb. 


Gets the current value of the systemwide clock. 
Converts a formatted string to a time/date structure. 
Returns the value of interval timers. 

Gets the date and time. 

Converts time units to broken-down UTC time. 


Converts a time (expressed as the number of seconds elapsed 
since 00:00:00, January 1, 1970) into hours, minutes, seconds, 
and so on. 


Converts a local-time structure into time since the Epoch. 


(continued on next page) 
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Function Description 


System Functions—Retrieving and Converting Date/Time Information 


nanosleep High-resolution sleep (REALTIME). Suspends a process from 
execution for the specified timer interval. 

setitimer Sets the value of interval timers. 

strftime, wcsftime Place characters into an array, as controlled by a specified 
format string. 

strptime Converts a character string into date and time values. 

time Returns the time elapsed since 00:00:00, January 1, 1970, in 
seconds. 

times Returns the accumulated times of the current process and of 
its terminated child processes. 

tzset Sets and accesses time-zone conversion. 

ualarm Sets or changes the timeout of interval timers. 

wesftime Uses date and time information stored in a tm structure to 


create a wide-character output string. 


System Function—Miscellaneous 


VAXCSCRTL_INIT Initializes the run-time environment and establishes an exit 
and condition handler, which makes it possible for HP C RTL 
functions to be called from other languages. 


Example 9-1 shows how the cuserid function is used. 


Example 9-1 Accessing the User Name 

/* CHAP_9 GET USER.C */ 
/* Using cuserid, this program returns the user name. */ 
#include <stdio.h> 


main () 


{ 


static char string[L_cuserid] ; 


cuserid(string) ; 
printf ("Initiating user: %s\n", string); 


If a user named TOLLIVER runs the program, the following is displayed on 
stdout: 


$ RUN EXAMPLE1 
Initiating user: TOLLIVER 


Example 9-2 shows how the getenv function is used. 
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Example 9-2 Accessing Terminal Information 


/* CHAP _9 GETTERM.C */ 
/* Using getenv, this program returns the terminal. */ 


#include <stdio.h> 
#include <stdlib.h> 


main () 


{ 


printf("Terminal type: %s\n", getenv("TERM")); 


Running Example 9-2 on a VT100 terminal in 132-column mode displays the 
following: 


$ RUN EXAMPLE3 
Terminal type: vt100-132 


Example 9-3 shows how to use getenv to find the user’s default login directory 
and how to use chdir to change to that directory. 


Example 9-3 Manipulating the Default Directory 


/* CHAP 9 CHANGE DIR.C */ 


/* This program performs the equivalent of the DCL command */ 
/* SET DEFAULT SYSSLOGIN. However, once the program exits, the */ 
/* directory is reset to the directory from which the program */ 
/* was run. */ 


#include <stdio.h> 
#include <unistd.h> 
#include <stdlib.h> 


main () 
{ 
char *dir; 
int i; 
dir = getenv("HOME") ; 
if ((i = chdir(dir)) != 0) { 
perror ("Cannot set directory") ; 
exit (0); 


printf ("Current directory: %s\n", dir); 
} 
Running Example 9-3 displays the following: 


$ RUN EXAMPLE4 
Current directory: dba0: [tolliver] 


$ 


Example 9—4 shows how to use the time, localtime, and strftime functions to 
print the correct date and time at the terminal. 
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Example 9-4 Printing the Date and Time 


/* CHAP 9 DATE TIME.C */ 
/* The time function returns the time in seconds; the localtime */ 
/* function converts the time to hours, minutes, and so on; */ 
/* the strftime function uses these values to obtain a string */ 
/* in the desired format. */ 


#include <time.h> 
#include <stdio.h> 


#define MAX STRING 80 


main () 


{ 


struct tm *time_ structure; 
time_t time val; 
char output_str [MAX STRING] ; 


time (&time_val) ; 
time_structure = localtime(&time val) ; 


/* Print the date */ 


strftime(output_str, MAX STRING, 
"Today is %A, %B sd, %Y", time structure) ; 


printf ("%s\n", output_str) ; 
/* Print the time using a 12-hour clock format. */ 


strftime(output_str, MAX STRING, 
"The time is %I1:%M %p", time structure) ; 


printf ("%s\n", output_str) ; 


} 


Running Example 9-4 displays the following: 


$ RUN EXAMPLE5 

Today is Thursday, May 20, 1993 
The time is 10:18 AM 

$ 


System Functions 9-5 


10 


Developing International Software 


This chapter describes typical features of international software and the features 
provided with the HP C Run-Time Library (RTL) that enable you to design and 
implement international software. 


See the Reference Section for more detailed information on the functions 
described in this chapter. 


10.1 Internationalization Support 


The HP C RTL has added capabilities to allow application developers to create 
international software. The HP C RTL obtains information about a language and 
a culture by reading this information from locale files. 


10.1.1 Installation 


If you are using these HP C RTL capabilities, you must install a separate kit 
to provide these files to your system. See the appendix "Installing OpenVMS 
Internationalization data kit" in the OpenVMS Upgrade and Installation Guide. 


On OpenVMS VAX systems, the save set VMSI18NOnn is provided on the same 
media as the OpenVMS operating system. 


On OpenVMS Alpha systems the save set is provided on the Layered Product CD, 
and is named VMSI18NOnn or ALPVMSI18NOn_07nn. 


To install this save set, follow the standard OpenVMS installation procedures 
using this save-set name as the name of the kit. There are several categories of 
locales that you can select to install. You can select as many locales as you need 
by answering the following prompts: 


Do you want European and US support? [YES]? 

Do you want Chinese GB18030 support (locale and Unicode converters) [YES]? 
Do you want Chinese support? [YES]? 

you want Japanese support? [YES]? 

Do you want Korean support? [YES]? 

Do you want Thai support? [YES]? 

Do you want the Unicode converters? [YES]? 


5 
jw) 
e) 


This kit also has an Installation Verification Procedure that we recommend you 
run to verify the correct installation of the kit. 


10.1.2 Unicode Support 


In OpenVMS Version 7.2, the HP C Run-Time Library added the Universal 
Unicode locale, which is distributed with the OpenVMS system, not with the 
VMSI18NOnn kit. The name of the Unicode locale is: 


UTF8-20 
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Like those locales shipped with the VMSI18NOnn kit, the Unicode locale is 
located at the standard location referred to by the SYS$118N_LOCALE logical 
name. 


The UTF8-20 Unicode is based on Unicode standard Version V2.0. The Unicode 
locale uses UCS-4 as wide-character encoding and UTF-8 as multibyte character 
encodings. 


HP C RTL also includes converters that perform conversions between Unicode 
and any other supported character sets. The expanded set of converters includes 
converters for UCS-2, UCS-4, and UTF-8 Unicode encoding. The Unicode 
converters can be used by the ICONV CONVERT utility and by the iconv family 
of functions in the HP C Run-Time Library. 


In OpenVMS Version 7.2, the HP C Run-Time Library added Unicode character 
set converters for Microsoft Code Page 437. 


10.2 Features of International Software 


International software is software that can support multiple languages and 
cultures. An international program should be able to: 


e Display messages in the user’s own language. This includes screen displays, 
error messages, and prompts. 


e Handle culture-specific information such as: 


— Date and time formatting 


The conventions for representing dates and times vary from one country 
to another. For example, in the US the month is given first; in the UK 
the day is specified first. Therefore, the date 12/5/1993 is interpreted as 
December 5, 1993 in the US, and as May 12, 1993 in the UK. 


— Numeric formatting 


The character that represents the decimal point (the radix character) and 
the thousands separator character vary from one country to another. For 
example, in the UK the period (.) is used to represent the radix character, 
and the comma is used as a separator. However, in Germany, the comma 
is used as the radix character and the period is the separator character. 
Therefore, the number 2,345.67 in the UK is the same as 2.345,67 in 
Germany. 


— Monetary formatting 


Currency values are represented by different symbols and can be 
formatted using a variety of separator characters, depending on the 
currency. 


e Handle different coded character sets (not just ASCID. 
e Handle a mixture of single and multibyte characters. 


e Provide multipass string comparisons. 


String comparison functions such as strcmp compare strings by comparing the 
codepoint values of the characters in the strings. However, some languages 
require more complex comparisons to correctly sort strings. 
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To meet the previous requirements, an application should not make any 
assumptions about the language, local customs, or the coded character set used. 
All this localization data should be defined separately from the program, and only 
bound to it at run time. 


The rest of this chapter describes how you can create international software using 
HP C. 


10.3 Developing International Software Using HP C 


The HP C environment provides the following facilities to create international 
software: 


e A method for separating localization data from a program. 


Localization data is held in a database known as a locale. This stores all the 
language and culture information required by a program. See Section 10.4 for 
details of the structure of locales. 


A program specifies what locales to use by calling the setlocale function. 
See Section 10.5 for more information. 


e A method of separating message text from the program source. 


This is achieved using message catalogs that store all the messages for an 
application. The message catalog is linked to the application at run time. 
This means that the messages can be translated into different languages and 
then the required language version is selected at run time. See Section 10.6. 


e HPC RTL functions that are sensitive to localization data. 
The HP C RTL includes functions for: 


— Converting between different codesets. See Section 10.7. 
-— Handling culture-specific information. See Section 10.8. 
— Multipass string collation. See Section 10.10. 


e A special wide-character data type defined in the HP C RTL makes it easier 
to handle codesets that have a mixture of single and multibyte characters. A 
set of functions is also defined to support this wide-character data type. See 
Section 10.9. 


10.4 Locales 


A locale consists of different categories, each of which determines one aspect of 
the international environment. Table 10-1 lists the categories in a locale and 
describes the information in each. 
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Table 10-1 Locale Categories 


Category Description 

LC_COLLATE Contains information about collating sequences. 

LC_CTYPE Contains information about character classification. 

LC_MESSAGES Defines the answers that are expected in response to yes/no 
prompts. 

LC_MONETARY Contains monetary formatting information. 

LC_NUMERIC Contains information about formatting numbers. 

LC_TIME Contains time and date information. 


The locales provided reside in the directory defined by the SYS$118N_LOCALE 
logical name. The file-naming convention for locales is: 


language_country_codeset.locale 
Where: 


e language is the mnemonic for the language. For example, EN indicates an 
English locale. 


e country is the mnemonic for the country. For example, GB indicates a British 
locale. 


e codeset is the name of the ISO standard codeset for the locale. For example, 
ISO8859-1 is the ISO 8859 codeset for the Western European languages. See 
Section 10.7 for more information about the codesets supported. 


10.5 Using the setlocale Function to Set Up an International 
Environment 


An application sets up its international environment at run time by calling the 
setlocale function. The international environment is set up in one of two ways: 


e The environment is defined by one locale. In this case, each of the locale 
categories is defined by the same locale. 


e Categories are defined separately. This lets you define a mixed environment 
that uses different locales depending on the operation performed. For 
example, if an English user has some Spanish files that are to be processed 
by an application, the LC_COLLATE category could be defined by a Spanish 
locale while the other categories are defined by an English locale. To do this 
you would call setlocale once for each category. 


The syntax for the setlocale function is: 
char “setlocale(int category, const char *locale) 
Where: 


e category is either the name of a category, or LC_ALL. Specifying LC_ALL 
means that all the categories are defined by the same locale. Specify a 
category name to set up a mixed environment. 


e locale is one of the following: 


— The name of the locale to use. 
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If you want users to specify the locale interactively, your application 
could prompt the user for a locale name, and then pass the name as an 
argument to the setlocale function. A locale name has the following 
format: 


language_country.codeset [@modifier] 


For example, setlocale(LC_ COLLATE, "en US.IS08859-1") selects the 
locale en_US.ISO8859-1 for the LC_COLLATE category. 


This causes the function to use logical names to determine the locale for 
the category specified. See Specifying the Locale Using Logical Names for 
details. 


If an application does not call the setlocale function, the default locale is the C 
locale. This allows such applications to call those functions that use information 
in the current locale. 


Specifying the Locale Using Logical Names 


If the setlocale function is called with "" as the locale argument, the function 
checks for a number of logical names to determine the locale name for the 
category specified. 


There are a number of logical names that users can set up to define their 
international environment: 


e Logical name corresponding to a category 


For example, the LC_NUMERIC logical name defines the locale associated 
with the LC_NUMERIC category within the user’s environment. 


e LC_ALL 
e LANG 
The LANG logical name defines the user’s language. 


In addition to the logical names defined by a user, there are a number of 
systemwide logical names, set up during system startup, that define the default 
international environment for all users on a system: 


e SYS$category 


Where category is the name of a category. This specifies the system default 
for that category. 


e SYS$LC_ALL 
e SYS$LANG 
The setlocale function checks for user-defined logical names first, and if these 
are not defined, it checks the system logical names. 
10.6 Using Message Catalogs 


An important requirement for international software is that it should be able to 
communicate with the user in the user’s own language. The messaging system 
enables program messages to be created separately from the program source, and 
linked to the program at run time. 


Messages are defined in a message text source file, and compiled into a message 
catalog using the GENCAT command. The message catalog is accessed by a 
program using the functions provided in the HP C RTL. 
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The functions provided to access the messages in a catalog are: 
e The catopen function, which opens a specified catalog ready for use. 


e The catgets function, which enables the program to read a specific message 
from a catalog. 


e The catclose function, which closes a specified catalog. Open message 
catalogs are also closed by the exit function. 


For information on generating message catalogs, see the GENCAT command 
description in the OpenVMS system documentation. 


10.7 Handling Different Character Sets 


The HP C RTL supports a number of state-independent codesets and codeset 
encoding schemes that contain the ASCII encoded Portable Character Set. It does 
not support state-dependent codesets. The codesets supported are: 


e ISO8859-n 


where n = 1,2,5,7,8 or 9. This covers codesets for North America, Europe 
(West and East), Israel, and Turkey. 


e eucJP, SJIS, DECKANJI, SDECKANJI: Codesets used in Japan. 


e eucTW, DECHANYU, BIG5, DECHANZI: Chinese codesets used in China 
(PRC), Hong-Kong, and Taiwan. 


e DECKOREAN: Codeset used in Korea. 
10.7.1 Charmap File 


The characters in a codeset are defined in a charmap file. The charmap files 
supplied by HP are located in the directory defined by the SYS$118N_LOCALE 
logical name. The file type for a charmap file is .CMAP. 


10.7.2 Converter Functions 


As well as supporting different coded character sets, the HP C RTL provides 
the following converter functions that enable you to convert characters from one 
codeset to another: 


e iconv_open—Specifies the type of conversion. It allocates a conversion 
descriptor required by the iconv function. 


e iconv—Converts characters in a file to the equivalent characters in a different 
codeset. The converted characters are stored in a separate file. 


e iconv_close—Deallocates a conversion descriptor and the resources allocated 
to the descriptor. 


10.7.3 Using Codeset Converter Files 


The file-naming convention for codeset converters is: 
fromcode_tocode. iconv 


Where fromcode is the name of the source codeset, and tocode is the name of the 
codeset to which characters are converted. 


You can add codeset converters to a given system by installing the converter files 
in the directory pointed by the logical name SYS$118N_ICONV. 
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Codeset converter files can be implemented either as table-based conversion files 
or as algorithm-based converter files created as OpenVMS shareable images. 
Creating a Table-Based Conversion File 

The following summarizes the necessary steps to create a table-based codeset 
converter file: 


1. Create a text file that describes the mapping between any character from the 
source codeset to the target codeset. For the format of this file, see the DCL 
command ICONV COMPILE in the OpenVMS New Features Manual, which 
processes such a file and creates a codeset converter table file. 


2. Copy the resulting file from the previous step to the directory pointed by the 
logical SYS$I18N_ICONV, assuming you have the privilege to do so. 

Creating an Algorithm-Based Conversion File 

To create an algorithm-based codeset converter file implemented as a shareable 

image, follow these steps: 


1. Create C source files that implement the codeset converter. The API is 
documented in the public header file <iconv.h> as follows: 


e The universal entry point u_iconv_open is called by the HP C RTL 
routine iconv_open to initialize a conversion. 


e _u_iconv_open returns to iconv_ open a pointer to the structure 
iconv extern obj t. 


e Within this structure, the converter exports its own conversion entry point 
and conversion close routine, which are called by the HP C RTL routines 
iconv and iconv_close, respectively. 


e The major and minor identifier fields are required by iconv_open to 
test for a possible mismatch between the library and the converter. 
The converter usually assigns the constants __ICONV_MAJOR and 
__ICONV_MINOR, defined in the <iconv.h> header file. 


e The field tcs_mb_cur_max is used only by the DCL command ICONV 
CONVERT to optimize its buffer usage. This field reflects the maximum 
number of bytes that comprise a single character in the target codeset, 
including the shift sequence (if any). 


2. Compile and link the modules that comprise the codeset converter as an 
OpenVMS shareable image, making sure that the file name adheres to the 
preceding conventions. 


3. Copy the resulting file from the previous step to the directory pointed by the 
logical SYS$I18N_ICONV, assuming you have the privilege to do so. 


Some Final Notes 


By default, SYS$I118N_ICONV is a search list where the first directory in the 
list SYS$SYSROOT:[SYS$I18N.ICONV.USER] is meant for use as a site-specific 
repository for iconv codeset converters. 


The number of codesets and locales installed vary from system to system. Check 
the SYS$I18N directory tree for the codesets, converters, and locales installed on 
your system. 


Developing International Software 10-7 


10.8 Handling Culture-Specific Information 


Each locale contains the following cultural information: 


Date and time information 


The LC_TIME category defines the conventions for writing date and time, the 
names of the days of the week, and the names of months of the year. 


Numeric information 


The LC_NUMERIC category defines the conventions for formatting 
nonmonetary values. 


Monetary information 


The LC_MONETARY category defines currency symbols and the conventions 
used to format monetary values. 


Yes and no responses 


The LC_MESSAGES category defines the strings expected in response to 
yes/no questions. 


You can extract some of this cultural information using the nl_langinfo function 
and the localeconv function. See Section 10.8.1. 


10.8.1 Extracting Cultural Information From a Locale 


The nl_langinfo function returns a pointer to a string that contains an item of 
information obtained from the program’s current locale. The information you can 
extract from the locale is: 


Date and time formats 


The names of the days of the week, and months of the year in the local 
language 


The radix character 

The character used to separate groups of digits in nonmonetary values 
The currency symbol 

The name of the codeset for the locale 


The strings defined for responses to yes/no questions 


The localeconv function returns a pointer to a data structure that contains 
numeric formatting and monetary formatting data from the LC_NUMERIC and 
LC_MONETARY categories. 


10.8.2 Date and Time Formatting Functions 


The functions that use the date and time information are: 


strftime—Takes date and time values stored in a data structure and formats 
them into an output string. The format of the output string is controlled by a 
format string. 


strptime—Converts a string (of type char) into date and time values. A 
format string defines how the string is interpreted. 


wcesftime—Does the same as strftime except that it creates a wide-character 
string. 
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10.8.3 Monetary Formatting Function 
The strfmon function uses the monetary information in a locale to convert a 
number of values into a string. The format of the string is controlled by a format 
string. 

10.8.4 Numeric Formatting 


The information in LC_NUMERIC is used by various functions. For example, 
strtod, wcstod, and the print and scan functions determine the radix character 
from the LC_NUMERIC category. 


10.9 Functions for Handling Wide Characters 


A character can be represented by single-byte or multibyte values depending 

on the codeset. To make it easier to handle both single-byte and multibyte 
characters in the same way, the HP C RTL defines a wide-character data type, 
wchar_t. This data type can store characters that are represented by 1-, 2-, 3-, or 
4-byte values. 


The functions provided to support wide characters are: 

e Character classification functions. See Section 10.9.1. 

e Case conversion functions. See Section 10.9.2. 

e Input and output functions. See Section 10.9.3. 

e Multibyte to wide-character conversion functions. See Section 10.9.4. 
e Wide-character to multibyte conversion functions. See Section 10.9.4. 
e Wide-character string manipulation functions. See Section 10.9.5. 


e Wide-character string collation and comparison functions. See Section 10.10. 


10.9.1 Character Classification Functions 


The LC_CTYPE category in a locale classifies the characters in the locale’s 
codeset into different types (alphabetic, numeric, lowercase, uppercase, and so 
on). There are two sets of functions, one for wide characters and one for single- 
byte characters, that test whether a character is of a specific type. The is* 
functions test single-byte characters, and the isw* functions test wide characters. 


For example, the iswalnum function tests if a wide character is classed as either 

alphabetic or numeric. It returns a nonzero value if the character is one of these 
types. For more information about the classification functions, see Chapter 3 and 
the Reference Section. 


10.9.2 Case Conversion Functions 


The LC_CTYPE category defines mapping between pairs of characters of the 
locale. The most common character mapping is between uppercase and lowercase 
characters. However, a locale can support more than just case mappings. 


Two functions are provided to map one character to another according to the 
information in the LC_CTYPE category of the locale: 


e wctrans—Looks for the named mapping (predefined in the locale) between 
characters. 


e towctrans—Maps one character to another according to the named mapping 
given to the wctrans function. 
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Two functions are provided for character case mapping: 
e towlower—Maps an uppercase wide character to its lowercase equivalent. 
e towupper—Maps a lowercase wide character to its uppercase equivalent. 


For more information about these functions, see the Reference Section. 


10.9.3 Functions for Input and Output of Wide Characters 
The set of input and output functions manages wide characters and wide- 
character strings. 
Read Functions 
The functions for reading wide characters and wide-character strings are fgetwc, 
fgetws, getwc, and getwchar. 


There is also an ungetwc function that pushes a wide character back into the 
input stream. 

Write Functions 

The functions for writing wide characters and wide-character strings are fputwc, 
fputws, putwc, and putwchar. 

Scan Functions 

All the scan functions allow for a culture-specific radix character, as defined in 
the LC_NUMERIC category of the current locale. 


The %lc, %C, %ls, and %S conversion specifiers enable the scan functions 
fwscanf, wscanf, swscanf, fscanf, scanf, and sscanf to read in wide characters. 


Print Functions 


All the print functions can format numeric values according to the data in the 
LC_NUMERIC category of the current locale. 


The %lc, %C and %ls, %S conversion specifiers used with print functions convert 
wide characters to multibyte characters and print the resulting characters. 


See Chapter 2 for details of all input and output functions. 
10.9.4 Functions for Converting Multibyte and Wide Characters 


Wide characters are used internally by an application to manage single-byte 
or multibyte characters. However, text files are generally stored in multibyte 
character format. To process these files, the multibyte characters need converting 
to wide-character format. This can be achieved using the following functions: 


e mbtowc, mbrtowc, btowc—Convert one multibyte character to a wide character. 


e mbsrtowcs, mbstowcs—Convert a multibyte character string to a wide- 
character string. 


Similarly, the following functions convert wide characters into their multibyte 
equivalent: 


e wertomb, wctomb, wctob—Convert a single wide character to a multibyte 
character. 


e wcesrtombs, wcstombs—Convert a wide-character string to a multibyte 
character string. 


Associated with these conversion functions, the mblen and mbrlen functions are 
used to determine the size of a multibyte character. 
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Several of the wide-character functions take an argument of type "pointer to 
mbstate t", where mbstate t is an opaque datatype (like FILE or fpos t) 
intended to keep the conversion state for the state-dependent codesets. 


10.9.5 Functions for Manipulating Wide-Character Strings and Arrays 


The HP C RTL contains a set of functions (the wcs* and wmem* functions) that 
manipulate wide-character strings. For example, the wcscat function appends 
a wide-character string to the end of another string in the same way that the 
strcat function works on character strings of type char. 


See Chapter 3 for details of the string manipulation functions. 


10.10 Collating Functions 


In an international environment, string comparison functions need to allow for 
multipass collations. The collation requirements include: 


e Ordering accented characters. 


e Collating a character sequence as a single character. For example, ch in 
Spanish should be collated after c but before d. 


e Collating a single character as a two-character sequence. 
e Ignoring some characters. 


Collating information is stored in the LC_COLLATE category of a locale. The 
HP C RTL includes the strcoll and wcscoll functions that use this collating 
information to compare two strings. 


Multipass collations by strcoll or wescoll can be slower than using the strcmp 
or wcscmp functions. If your program needs to do many string comparisons using 
strcoll or wcscoll, it may be quicker to transform the strings once, using the 
strxfrm or wcsxfrm function, and then use the strcmp or wcscmp function. 


The term collation refers to the relative order of characters. The collation order 
is locale-specific and might ignore some characters. For example, an American 
dictionary ignores the hyphen in words and lists take-out between takeoff and 
takeover. 


Comparison, on the other hand, refers to the examination of characters for 
sameness or difference. For example, takeout and take-out are different words, 
although they may collate the same. 


Suppose an application sorts a list of words so it can later perform a binary 
search on the list to quickly retrieve a word. Using strcmp, take-in, take-out, and 
take-up would be grouped in one part of the table. Using strcoll and a locale 
that ignores hyphens, take-out would be grouped with takeoff and takeover, and 
would be considered a duplicate of takeout. To avoid a binary search finding 
takeout as a duplicate of take-out, an application would most likely use strcmp 
rather than strcoll for forming a binary tree. 
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Date/Time Functions 


This chapter describes the date/time functions available with HP C for OpenVMS 
Systems. For more detailed information on each function, see the Reference 


Section. 


Table 11-1 Date/Time Functions 


Function Description 

asctime Converts a broken-down time from localtime into a 26-character 
string. 

ctime Converts a time, in seconds, since 00:00:00, January 1, 1970 to an 
ASCII string of the form generated by the asctime function. 

ftime Returns the elapsed time since 00:00:00, January 1, 1970 in the 
structure pointed to by its argument. 

getclock Gets the current value of the systemwide clock. 

gettimeofday Gets the date and time. 

gmt ime Converts time units to GMT (Greenwich Mean Time). 

localtime Converts a time (expressed as the number of seconds elapsed since 
00:00:00, January 1, 1970) into hours, minutes, seconds, and so on. 

mktime Converts a local time structure to a calendar time value. 

time Returns the time elapsed since 00:00:00, January 1, 1970, in seconds. 

tzset Sets and accesses time-zone conversion. 


Also, the time-related information returned by fstat and stat uses the new 
date/time model described in Section 11.1. 


11.1 Date/Time Support Models 


Beginning with OpenVMS Version 7.0, the HP C RTL changed its date/time 
support model from one based on local time to one based on Universal 


Coordinated Time (UTC). This allows the HP C RTL to implement ANSI C/POSIX 
functionality that previously could not be implemented. A UTC time-based model 
also makes the HP C RTL compatible with the behavior of the Tru64 UNIX time 
functions. 


By default, newly compiled programs will generate entry points into UTC-based 
date/time routines. 


For compatibility with OpenVMS systems prior to Version 7.0, previously 
compiled programs that relink on an OpenVMS Version 7.0 system will retain 
local-time-based date/time support. Relinking alone will not access UTC support. 


Compiling programs with the DECC_V4_SOURCE and _VMS_V6_SOURCE 
feature-test macros defined will also enable local-time-based entry points. That 
is, the new OpenVMS Version 7.0 date/time functions will not be enabled. 


Date/Time Functions 11-1 


Functions with both UTC-based and local-time-based entry points are: 


ctime mktime 
fstat stat 
ftime strftime 
gmt ime time 
localtime wesftime 


Note 


Introducing a UTC-based, date/time model implies a certain loss of 
performance because time-related functions supporting UTC must read 
and interpret time-zone files instead of doing simple computations in 
memory as was done for the date/time model based on local time. 


To decrease this performance degradation, OpenVMS Version 7.1 and 
higher can maintain the processwide cache of time-zone files. The size of 
the cache (that is, the number of files in the memory) is determined by 
the value of the DECC$TZ_CACHE_SIZE logical name. The default value 
is 2. 

Because the time-zone files are relatively small (about 3 blocks each), 
consider defining DECC$TZ_CACHE_SIZE as the maximum number of 
time zones used by the application. For example, the default cache size 
fits an application that does not switch time zones during the run and 
runs on a system where the TZ environment variable is defined with both 
Standard and Summer time zone. 


11.2 Overview of Date/Time Functions 


In the UTC-based model, times are represented as seconds since the Epoch. The 
Epoch is defined as the time 0 hours, 0 minutes, 0 seconds, January 1, 1970 UTC. 
Seconds since the Epoch is a value interpreted as the number of seconds between 
a specified time and the Epoch. 


The functions time and ftime return the time as seconds since the Epoch. 


The functions ctime, gmtime, and localtime take as their argument a time value 
that represents the time in seconds from the Epoch. 


The function mktime converts a broken-down time, expressed as local time, into a 
time value in terms of seconds since the Epoch. 


The values st_ctime, st_atime, and st_mtime returned in the stat structure by 
the stat and fstat functions are also in terms of UTC. 


Time support new to OpenVMS Version 7.0 includes the functions tzset, 
gettimeofday, and getclock, and the external variables tzname, timezone, and 
daylight. 


The UTC-based time model enables the HP C RTL to: 


e Implement the ANSI C gmtime function, which returns a structure in terms 
of GMT time. 


e Specify the ANSI tm_isdst field of the tm structure, which specifies whether 
daylight savings time is in effect. 
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e Provide time-related POSIX and X/Open extensions (such as the tzset 
function (which lets you get time information from any time zone), and the 
external variables tzname, timezone, and daylight. 


e Correctly compute the local time for times in the past, something that the 
time functions like localtime need to do. 


e Enable localtime and gmtime, through the use of feature-test macros (see 
Section 1.5), to return two additional fields: tm_zone (an abbreviation of the 
time-zone name) and tm_gmtoff (the offset from UTC in seconds) in the tm 
structure they return. 


11.3 HP C RTL Date/Time Computations—UTC and Local Time 


Universal Coordinated Time (UTC) is an international standard for measuring 
time of day. Under the UTC time standard, zero hour occurs when the Greenwich 
Meridian is at midnight. UTC has the advantage of always increasing, unlike 
local time, which can go backwards/forwards depending on daylight saving time. 


Also, UTC has two additional components: 
e A measure of inaccuracy (optional) 


e A time-differential factor, which is an offset applied to UTC to derive local 
time. 


The time-differential factor associates each local time zone with UTC; the 
time differential factor is applied to UTC to derive local time. (Local times 
can vary up to —12 hours West of the Greenwich Meridian and +13 hours East 
of it). 


For the HP C RTL time support to work correctly on OpenVMS Version 7.0 and 
higher, the following must be in place: 


e Your OpenVMS system must be correctly configured to use a valid 
OpenVMS TDF. Make sure this is set correctly by checking the value of 
the SYS$TIMEZONE_DIFFERENTIAL logical. This logical should contain 
the time difference added to UTC to arrive at your local time. 


e Your OpenVMS installation must correctly set the local time zone that 
describes the location that you want to be your default local time zone. In 
general, this is the local time zone in which your system is running. 


For more information, see the section on setting up your system to compensate 
for different time zones in your OpenVMS System Manager’s Manual: Essentials. 


The HP C RTL uses local time-zone conversion rules to compute local time from 
UTC, as follows: 


1. The HP C RTL internally computes time in terms of UTC. 


2. The HP C RTL then uses time-zone conversion rules to compute a time- 
differential factor to apply to UTC to derive local time. See the tzset 
function in the Reference Section of this manual for more information on the 
time-zone conversion rules. 


By default, the time-zone conversion rules used for computing local time 

from UTC are specified in time-zone files defined by the SYS$LOCALTIME 

and SYS$POSIXRULES system logicals. These logicals are set during an 
OpenVMS installation to point to time-zone files that represent the system’s best 
approximation to local wall-clock time: 
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e SYS$LOCALTIME defines the time-zone file containing the default conversion 
rules used by the HP C RTL to compute local time. 


e SYS$POSIXRULES defines the time-zone file that specifies the default rules 
to be applied to POSIX style time zones that do not specify when to change to 
summer time and back. 


SYS$POSIXRULES can be the same as SYS$LOCALTIME. See the tzset 
function for more information. 


11.4 Time-Zone Conversion Rule Files 


The time-zone files pointed to by the SYS$LOCALTIME and SYS$POSIXRULES 
logicals are part of a public-domain, time-zone support package installed on 
OpenVMS Version 7.0 and higher systems. 


This support package includes a series of source files that describe the time- 
zone conversion rules for computing local time from UTC in worldwide time 
zones. OpenVMS Version 7.0 and higher systems provide a time-zone compiler 
called ZIC. The ZIC compiler compiles time-zone source files into binary files 
that the HP C RTL reads to acquire time-zone conversion specifications. For 
more information on the format of these source files, see the OpenVMS system 
documentation for ZIC. 


The time-zone files are organized as follows: 


e The root time-zone directory is SYS$COMMON:|SYS$TIMEZONE.SYSTEM]. 
The system logical SYS$TZDIR is set during installation to point to this area. 


e Time-zone source files are found in 
SYS$COMMON:|[SYS$TIMEZONE.SYSTEM.SOURCES]. 


e Binary time-zone files use SYS$COMMON:|[SYS$TIMEZONE.SYSTEM] as 
their root directory. Some binaries reside in this directory while others reside 
in its subdirectories. 


e Binaries residing in subdirectories are time-zone files that represent 
specific time zones in a larger geographic area. For example, 
SYS$COMMON:|SYS$TIMEZONE.SYSTEM] contains a subdirectory for 
the United States and a subdirectory for Canada, because each of these 
geographic locations contains several time zones. Each time zone in the US is 
represented by a time-zone file in the Unites States subdirectory. Each time 
zone in Canada is represented by a time-zone file in the Canada subdirectory. 


Several of the time-zone files have names based on acronyms for the areas that 
they represent. Table 11-2 lists these acronyms. 


Table 11-2 Time-zone Filename Acronyms 


Time-Zone 

Acronym Description 

CET Central European Time 
EET Eastern European Time 
Factory Specifies No Time Zone 
GB-Eire Great Britain/Ireland 


(continued on next page) 
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Table 11-2 (Cont.) Time-zone Filename Acronyms 


Time-Zone 

Acronym Description 

GMT Greenwich Mean Time 

NZ New Zealand 

NZ-CHAT New Zealand, Chatham Islands 
MET Middle European Time 

PRC Peoples Republic of China 

ROC Republic of China 

ROK Republic of Korea 

SystemV Specific to System V operating system 
UCT Universal Coordinated Time 
US United States 

UTC Universal Coordinated Time 
Universal Universal Coordinated Time 
W-SU Middle European Time 

WET Western European Time 


A mechanism is available for you to define and implement your own time-zone 
rules. For more information, see the OpenVMS system documentation on the ZIC 
compiler and the description of tzset in the reference section of this manual. 


Also, the SYS$LOCALTIME and SYS$POSIXRULES system logicals can be 
redefined to user-supplied time zones. 


11.5 Sample Date/Time Scenario 


The following example and explanation shows how to use the HP C RTL time 
functions to print the current time: 


#include <stdio.h> 
#include <time.h> 


main () 


time_t t; 


t = time((time_t)0); 
printf ("The current time is: %s\n",asctime (localtime (&t))); 


This example: 


1. Calls the time function to get the current time in seconds since the Epoch, in 
terms of UTC. 


2. Passes this value to the localtime function, which uses time-conversion 
information as specified by tzset to determine which time-zone conversion 
rules should be used to compute local time from UTC. By default, these rules 
are specified in the file defined by SYS$LOCALTIME: 


a. For a user in the Eastern United States interested in their local 
time, SYS$LOCALTIME would be defined during installation to 
SYS$COMMON:|[SYS$ZONEINFO.US]EASTERN, the time-zone file 
containing conversion rules for the Eastern U.S. time zone. 
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b. If the local time falls during daylight savings time (DST), 
SYS$COMMON:|[SYS$ZONEINFO.US]JEASTERN indicates that a 
time differential factor of —4 hours needs to be applied to UTC to get local 
time. 
If the local time falls during Eastern standard time (EST), 
SYS$COMMON:[SYS$ZONEINFO.US]JEASTERN indicates that a 
time differential factor of —5 hours needs to be applied to UTC to get local 
time. 


c. The HPC RTL applies —4 (DST) or —5 (EST) to UTC, and localtime 
returns the local time in terms of a tm structure. 


3. Pass this tm structure to the asctime function to print the local time in a 
readable format. 
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Symbolic Links and POSIX Pathname Support 


OpenVMS Version 8.3 and higher provides Open Group compliant symbolic 

link support and POSIX pathname processing support. This support will help 
partners and customers who port UNIX and LINUX applications to OpenVMS 

or who use a UNIX style development environment to reduce the application 
development costs and complexity previously associated with such porting efforts. 


The following OpenVMS features are provided to support symbolic links and 
POSIX pathname processing: 


The Open Group compliant symbolic-link functions symlink, readlink, 
unlink, realpath, lchown and lstat are added to the C Run-Time Library 
(C RTL) (see Section 12.3.3). 


Existing C RTL functions such as creat, open, delete, and remove, now 
behave in accordance with Open Group specifications for symbolic links (see 
Section 12.3.4). 


RMS allows the C RTL to implement the above-mentioned functions. 
RMS routines such as SYS$OPEN, SYS$CREATE, SYS$PARSE, and 
SYS$SEARCH now support symbolic links (see Section 12.4). 


The contents of symbolic links on OpenVMS are interpreted as POSIX 
pathnames when encountered during pathwalks and searches. POSIX 
pathnames are now supported in OpenVMS and are usable through C RTL 
and RMS interfaces (see Section 12.1.2.) 


A new feature logical DECC$POSIX_COMPLIANT_PATHNAMES is added to 
the C RTL to indicate that an application is operating in a POSIX-compliant 
mode. In POSIX-compliant mode, only the newest version of a file is visible. 
Access to multiple versions of a file is not allowed (see Section 12.3.1). 


The DCL command CREATE/SYMLINK is used to create a symbolic link. 
(see Section 12.2.1). 


The DCL command SET ROOT is used to create the system POSIX root (see 
Section 12.5). 


Two GNV utilities, mmt and umnt, are provided to set mount points (see 
Section 12.7). 


DCL commands and utilities are modified to behave appropriately when 
acting on and encountering symbolic links (see Section 12.9). 


The TCP/IP Services for OpenVMS Network File System (NFS) client and 
server are enhanced to support symbolic links on ODS5 volumes. 


Relevant GNV utilities such as 1n (which can create a symbolic link) and 1s 
(which can display the contents of a symbolic link) are updated to provide 
access to and management of symbolic links (see Sections 12.2.2 and 12.10). 
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12.1 POSIX Pathnames and Filenames 


A POSIX pathname is a non-empty character string consisting of 0 or more 
filenames, separated by a / (the path delimiter). The path delimiter can be the 
first or last character of a pathname and is also the separator between filenames. 
Multiple consecutive delimiters are valid and are equivalent to a single delimiter. 


POSIX filenames can consist of all ASCII characters except / (the path delimiter) 
and NUL, which is used as a string terminator in many APIs. (On OpenVMS 
systems, POSIX filenames are also currently restricted to not contain the ? or * 
character.) A filename is sometimes referred to as a pathname component. 


12.1.1 POSIX Pathname Interpretation 


If the pathname begins with a /, it is considered to be an absolute pathname, and 
pathname processing begins at the device and directory specified by the POSIX 
root (see Section 12.5 for the method to define the root). 


If the pathname does not begin with a /, it is considered to be a relative 
pathname, and pathname processing begins with the current working directory. 


See Section 12.6 for how OpenVMS interprets the current working directory. 


12.1.1.1_| The POSIX Root Directory 


The POSIX root directory is a directory that is used in pathname resolution for 
absolute pathnames. 


The root directory, is the top-most node of the hierarchy, and has itself as its 
parent directory. The pathname of the root directory is /, and the parent directory 
of the root directory is /. Note that only files and directories actually entered in 
the root directory are accessible with a POSIX pathname. For additional details, 
see the note in Section 12.3.1. 


See Section 12.5 for defining the POSIX root on OpenVMS. 


12.1.1.2 Symbolic Links 


A symbolic link is a special kind of file that points to another file. It is a directory 
entry that associates a filename with a text string that is interpreted as a POSIX 
pathname when accessed by certain services. Most operations that access a 
symbolic link are rerouted to the object to which the text contents refer; if that 
object does not exist, the operation fails. A symbolic link is implemented on 
OpenVMS as a file of organization SPECIAL and type SYMBOLIC_LINK. 


A symbolic link can specify an absolute pathname or a relative pathname. The 
relative path in a symbolic link is relative to the location of the link. For example, 
a symbolic link whose content begins with the path ".." refers to its parent 
directory. If the symbolic link is moved to another directory, it refers to its new 
parent directory. Note that the path specified by a symbolic link is a POSIX 
pathname and is subject to the restrictions described in Section 12.3.1. 


See Section 12.2 for symbolic link usage on OpenVMS. 


12.1.1.3 Mount Points 


A mount point is a location (in fact, a directory) where a file system is attached. 
The UNIX term file system is essentially equivalent to the OpenVMS concept of 
a disk volume. After a mount point is established, any contents of the original 
directory are inaccessible. 


Mount points do not persist across reboots. 
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See Section 12.7 for establishing mount points on OpenVMS. 


12.1.1.4 Reserved Filenames. and.. 
There are two reserved POSIX filenames: 


. (the current directory) 


.. (the parent directory) 


12.1.1.5 Character Special Files 


On UNIX systems, a special file is associated with a particular hardware device 
or other resource of the computer system. The operating system uses character 
special files, sometimes called device files, to provide I/O access to specific 
character devices. 


Special files, at first glance, appear to be just like ordinary files, in that they: 
e Have path names that appear in a directory 

e Have the same access protection as ordinary files 

e Can be used in almost every way that ordinary files can be used 


However, there is an important difference between the two: an ordinary file is a 
logical grouping of data recorded on disk, whereas a special file corresponds to a 
device entity. Examples are: 


e An actual device, such as a line printer 
e A logical subdevice, such as a large section of the disk drive 


e A pseudo device, such as the physical memory of the computer (/dev/mem), the 
terminal file (/dev/tty), or the null file (/dev/nul1). 


Only the null special file (/dev/null) is supported. This file is created during the 
GNV configuration procedure. Data written on the null special file is discarded. 
Reads from a null special file always return 0 bytes. 


12.1.2 Using POSIX Pathnames with OpenVMS Interfaces 


POSIX compliant pathnames can be passed to most OpenVMS applications, 
utilities, and APIs. 


The existing DCL convention of doubling any quote character that is in a quoted 
string has been adopted. 


Also, in order to avoid constraints on future use of quoted strings for pathnames 

(for example, to support another syntactic variation, such as Windows-compatible 
names), the leading tag “UP* is required on the quoted pathname to identify it as 
a POSIX pathname to DCL, RMS, and OpenVMS utilities. It is not required for 

the C RTL or GNV. 


So, for example, /a/b/c becomes "“UP*/a/b/c" and /a/b"/c becomes "“UP*/a 
/b" wiaW, 


Throughout the remainder of this chapter, the term POSIX pathname refers to 
the unmodified pathname (for example, /a/b/c) and quoted pathname refers to 
our quoted, tagged pathname (for example, "“UP*/a/b/c"). 
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12.1.2.1 Special Considerations with POSIX Filenames 
When a user creates a file on OpenVMS using a POSIX filename, it would be ideal 
if the filename viewed as an OpenVMS filename were the same. For example, 
when a user asks to create a file with POSIX filename a.b, OpenVMS could create 
a file with the name a.b; (where ; represents the file version). 


But because one of the components of an OpenVMS filename is the file type 
(consisting of at least a period), POSIX filenames without a period cannot be 
mapped in as direct a fashion (for example, POSIX filename a cannot be mapped 
to OpenVMS filename a;). The reasonable solution is for OpenVMS to append 
a period (representing a null file-type field) so that POSIX filename a becomes 
OpenVMS filename a. ; 


Note that OpenVMS appends a period (or null type) even to a POSIX filename 
that itself ends in a period. This is necessary to distinguish POSIX filenames a. 
and a from each other. 


Furthermore, OpenVMS directories have a type and version of .DIR;1. When 

a directory of POSIX filename a is created on OpenVMS, it is created with an 
OpenVMS filename of a.DIR;1. And because a.DIR is a valid POSIX filename, 

it needs to be distinguished from a directory with POSIX filename a residing in 
the same directory. So OpenVMS adds a period (or null type) to POSIX filenames 
ending in .DIR (so a file with POSIX filename a.DIR becomes a.DIR. ;). 


Keeping the above rules in mind, the following are POSIX filenames that are 
unmodified on OpenVMS, except for adding a version: 


POSIX filename OpenVMS name Type Version Displayed by DIR as 


a.b a me) : a.b; 
a.b; a .b; ; a.b;; 
a.b;2 a .b;2 : a.bj2; 


The following are examples of POSIX filenames that end with a period (.) or .DIR 
and, therefore, have a period appended when creating the OpenVMS filename: 


POSIX filename OpenVMS name Type Version Displayed by DIR as 


a a . aa} 

a. a. i a*..; 
a.. coe i a oie 
a.b. a.b. ; ab eet 
a.DIR a.DIR ; a*.DIR.; 


Finally, OpenVMS will add .DIR;1 to the end of any POSIX directory: 


POSIX filename OpenVMS name Type Version Displayed by DIR as 


a a .DIR 1 a.DIR;1 
a.dir a.dir .DIR il a*.dir.DIR;1 
a. a. .DIR al a*..DIR;1 


Note that both the OpenVMS filenames a.DIR;1 and a.; map to the POSIX 
filename a. Specifying the POSIX filename a will find either a.DIR;1 or a.; . If 
both are present, it finds a.; . The ambiguous mapping applies whether a.DIR;1 
is a directory or an ordinary file. 


All POSIX filenames that contain the * or ? characters are unmappable. This is 
an open issue to be addressed in a future release of OpenVMS. 
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12.1.2.2 Special Considerations with OpenVMS Filenames 


When mapping OpenVMS filenames to POSIX filenames (a feature provided by C 
RTL function readdir), the following rules apply: 


If the OpenVMS filename ends in .DIR;1 and the type of a file is a directory, then 
.DIR;1 is removed. For all other files, the ending semi-colon and version number 
are removed from the OpenVMS filename. 


If the OpenVMS filename ends in a period, the period is removed. 


All OpenVMS filenames that contain the / or NUL characters are unmappable 
and, therefore, not returned to the caller. 


OpenVMS directories ..DIR;1 and ...DIR;1 are unmappable because their 
corresponding POSIX filenames would be the special filenames . and... . 


OpenVMS file . is unmappable because the resulting POSIX filename would be a 
NULL string. 


12.2 Using Symbolic Links 
There are several ways to create a symbolic link: 
e Using the DCL command CREATE/SYMLINK (Section 12.2.1) 
e Using the ln -s utility within the GNV bash shell (Section 12.2.2) 
e Using the C RTL symlink function (Section 12.3.3) 


12.2.1 Creating and Using Symbolic Links with DCL 


The following examples show how to create and access symbolic links using DCL 
commands: 


Examples 


$ create/symlink="a/b.txt" link to_b.txt 


$ dir/date link _to_b.txt 
Directory DKBO: [TEST] 


link to _b.txt -> a/b.txt 
27-MAY-2005 09:45:15.20 


This example creates the symbolic link file link_to_b.txt with contents 
equal to the specified text string representing the pathname to which the 
symbolic link points, a/b.txt. Note that a/b.txt may or may not exist. Also 
note that the symlink file must be reachable from the POSIX root. 


$ type link to _b.txt 
STYPE-W-OPENIN, error opening DKBO:[TEST]LINK_TO B.TXT; as input 
-RMS-E-FNF, file not found 


To access the file referenced in a symbolic link, specify the symbolic link 
name on the command. The TYPE command error message in this example 
indicates that the file a/b.txt, referenced through the symbolic link 

link to_b.txt created in the first example, does not exist. 
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$ create [.a]b.txt 
This is a text file. 
Exit 


$ 
$ type link to _b.txt 
This is a text file 


$ 


This example creates the missing file b.txt. Once the referenced file exists, 
the TYPE command through the symbolic link is successful. 


Alternatively, you can create the file through the symbolic link: 


$ create link _to b.txt 
This is a text file. 
Exit 

$ dir [.a] 

Directory DKBO: [TEST.A] 


b.txt;1 


$ 
$ type link_to_b.txt 
This is a text file. 


$ 


12.2.2 Using Symbolic Links through GNV POSIX and DCL Commands 
You can create a symbolic link within the GNV bash shell with the 1n utility: 
bash$ In -s filename slinkname 


Most utilities and commands that reference slinkname are redirected so that they 
act on filename. Some commands, such as 1s, are symbolic link-aware, and show 
information about the link itself (such as its contents). 


A link can be removed with the rm command (which cannot be made to follow the 
link and remove what it points to). 


The examples that follow show how to manage symbolic links through GNV 
POSIX commands as compared with DCL commands. 


Examples 


" From GNV: 
bash$ cd /symlink_ example 
bash$ echo This is a test. > text 
bash$ cat text 

This is a test. 

bash$ In -s text LINKTOTEXT 

bashs 


From DCL: 


$ set def DISKSXALR: [PSXS$ROOT. symlink example] 
$ create text. 

This is a test. 

Exit 

$ type text. 

This is a test. 

$ create/symlink="text" LINKTOTEXT 


This example creates a symbolic link called LINKTOTEXT that points to a 
text file called text. 
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From GNV: 


bashs$ cat LINKTOTEXT 
This is a test. 
bashs 


From DCL: 


S$ type LINKTOTEXT. 
This is a test. 


$ 
This example displays the contents of the text file using the symbolic link. 


From GNV: 


bashs$ ls 

LINKTOTEXT text 

bashs ls -1l 

total 1 

lrwxr-x--- 1 SYSTEM 1 4 May 12 08:41 LINKTOTEXT -> text 
-Yw-Y----- 1 SYSTEM 1 16 May 12 08:40 text 

bashs 


From DCL: 
$ DIR 
Directory DISKSXALR: [PSXSROOT. symlink example] 
LINKTOTEXT. ;1 text.;1 
Total of 2 files. 
$ DIR/DATE 
Directory DISKSXALR: [PSXSROOT. symlink example] 


LINKTOTEXT.;1 -> /symlink_example/text 
12-MAY-2005 08:46:31.40 
text.;1 12-MAY-2005 08:43:47.53 


Total of 2 files. 
$ 


This example displays the content of a symbolic link. Notice that when you do 
an ls or a DIR using switches that show any file attribute, then the content 
of the symbolic link is also displayed. 


From GNV: 


bash$ rm text 

bash$S cat LINKTOTEXT 

cat: linktotext: i/o error 
bashs rm LINKTOTEXT 


From DCL: 


$ DEL text.;1 

$ TYPE LINKTOTEXT. 

STYPE-W-OPENIN, error opening 

DISKSXALR: [PSXSROOT. symlink example] LINKTOTEXT.;1 as input 
-RMS-E-ACC, ACP file access failed 

-SYSTEM-F-FILNOTACC, file not accessed on channel 


$ DEL LINKTOTEXT. ;1 
$ 


This example deletes files. 
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12.3 C RTL Support 


The following sections describe POSIX-compliant pathname and symbolic link 
support in the C RTL. 


12.3.1 DECCS$POSIX_COMPLIANT_PATHNAMES Feature Logical 


In order for a POSIX-compliant user to have consistency between the pathnames 
stored in symbolic links and the pathnames used as input to C RTL functions, the 
C RTL provides a feature logical, DECC$POSIX_COMPLIANT_PATHNAMES, 

to allow an application to present POSIX-compliant pathnames to any C RTL 
function that accepts a pathname. 

By default DECC$POSIX_COMPLIANT_PATHNAMES is disabled, and the usual 
C RTL behavior prevails. Notice that this disabled mode includes interpretation 
of pathnames as UNIX style specifications and uses rules that are different and 
unrelated to POSIX-compliant pathname processing. 


To disable DECC$POSIX_COMPLIANT_PATHNAMES when necessary, DEFINE 
it to 0 or "DISABLE": 


$ DEFINE DECCSPOSIX COMPLIANT PATHNAMES 0 


To enable DECC$POSIX_COMPLIANT_PATHNAMES, set it to one of the 
following values: 
1 POSIX only - All pathnames are designated as POSIX style. 


2 lLeans POSIX - Pathnames that end in ":" or contain any of the bracket characters 
"[]<>", and that can be successfully parsed by the SYS$FILESCAN service, are 
designated as OpenVMS style. Otherwise, they are designated as POSIX style. 


3  Leans OpenVMS - The pathnames "." and". .", or pathnames that contain '"/" are 
designated as POSIX style. Otherwise, they are designated as OpenVMS style. 


4 OpenVMS only - All pathnames are designated as OpenVMS style. 


Note 


Modes 1 and 4 are not recommended because of interactions with other 
shareable libraries and utilities. 


With DECC$POSIX_COMPLIANT_PATHNAMES thus enabled, the C RTL 
examines pathnames to determine if they should be designated as POSIX 
style or OpenVMS style, following rules determined by the value assigned to 
DECC$POSIX_COMPLIANT_PATHNAMES. 


For example, to designate that most pathnames are to be POSIX-compliant: 
$ DEFINE DECCSPOSIX COMPLIANT PATHNAMES 2 


When the C RTL designates a pathname as POSIX style, it does not convert 
a POSIX pathname it receives into an OpenVMS file specification; instead, it 
converts the POSIX pathname into the quoted pathname format (previously 
described) and allows RMS to process the pathname as it would process a 
pathname found in a symbolic link. 


Note 


Under OpenVMS, the C RTL has historically provided additional 
functionality to UNIX programs: if a filename (or pathname) was given 
with an initial slash (/), and the C RTL could not find the named file 
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under the root, it would attempt to translate the name immediately 
following the slash as a logical name or a device name. For example, 

the filename /SYS$COMMON/SYSEXE/DCL.EXE refers to DCL.EXE in 
SYS$COMMON:|SYSEXE]. Another example: /$1$DKA500 refers to the 
device $1$DKA500:. With DECC$POSIX_COMPLIANT_PATHNAMES 
defined, logical names and device names are not supported. The only 
names that are valid are names of files and directories actually present in 
the root. This restriction will be removed in a future release of OpenVMS. 


Some older OpenVMS applications may depend on this older format. If 
you run such applications, you may want to place either symbolic links or 
mount points under the root to allow such filenames to continue to work. 


When DECC$POSIX_COMPLIANT_PATHNAMES is defined, the following C 
RTL feature logicals are ignored: 


DECC$ARGV_PARSE_STYLE 
DECC$DISABLE_POSIX_ROOT 
DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION 
DECC$EFS_CASE_PRESERVE 
DECC$EFS_CASE_SPECIAL 
DECC$EFS_CHARSET 
DECC$EFS_NO_DOTS_IN_DIRNAME 
DECC$ENABLE_TO_VMS_LOGNAME_CACHE 
DECC$FILENAME_UNIX_NO_VERSION 
DECC$FILENAME_UNIX_ONLY 
DECC$FILENAME_UNIX_REPORT 
DECC$NO_ROOTED_SEARCH_LISTS 
DECC$READDIR_DROPDOTNOTYPE 
DECC$READDIR_KEEPDOTDIR 
DECC$RENAME_ALLOW_DIR 
DECC$RENAME_NO_INHERIT 
DECC$UNIX_PATH_BEFORE_LOGNAME 


12.3.2 decc$to_vms, decc$from_vms, and decc$translate_vms 


When operating in POSIX-compliant mode, the C RTL function decc$to_vms 
converts a POSIX pathname into the RMS quoted pathname format. If an RMS 
quoted pathname is passed to either decc$from_vms or decc$translate _vms, 
these functions change the quoted pathname into a POSIX pathname by removing 
the quotes and the *UP* prefix (so, for example, "*UP*a/b" becomes a/b). When 
not in POSIX-compliant mode, these functions operate as they did previously. 


12.3.3 Symbolic Link Functions 


Table 12-1 lists and describes the symbolic-link functions in the HP C Run-Time 
Library (RTL). For more detailed information on each function, see the Reference 
Section. 
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Table 12-1 Symbolic Link Functions 


Function Description 


lchown Changes the owner and/or group of a file. If the file is a symbolic 


link, the owner of the symbolic link is modified (in contrast to 
chown which would modify the file that the symbolic link points to). 


Istat Retrieves information about the specified file. If the file is a 


symbolic link, information about the link itself is returned (in 
contrast to Stat, which would return information about the file 
that the symbolic link points to). 


readlink Reads the contents of a symbolic link and places them into a 


user-supplied buffer. 


realpath Returns an absolute pathname from the POSIX root. This 


function is only supported in POSIX-compliant modes; that is, 
with DECC$POSIX_COMPLIANT_PATHNAMES enabled. 


unlink Deletes a symbolic link from the system. 


symlink Creates a symbolic link containing the specified contents. 


12.3.4 Modifications to Existing Functions 


In addition to the previously described new functions, the following C RTL 
functions are modified to support symbolic links: 


creat 


When a new version of a file is created, and the named file already exists as a 
symbolic link, the file to which the symbolic link refers is created. 


open 


If the file_spec parameter refers to a symbolic link, the open function opens 
the file pointed to by the symbolic link. 


delete, remove 


When delete or remove is used to delete a symbolic link, the link itself is 
deleted, not the file to which it refers. 


Also, in accordance with the Open Group specification, an errno value of ELOOP 
is returned if a loop exists in the resolution of a symbolic link. 


12.3.5 Non POSIX-Compliant Behavior 


12.3.5.1 Multiple Versions of Files 

When using POSIX-compliant pathnames, if multiple versions of a file exist, you 
can access only the latest version of the file. Deleting a file results in the deletion 
of only the highest-numbered version of a file. 


12.3.5.2_ Ambiguous Filenames 
If the file "a" and directory "a.DIR;1" both exist in a directory, users in POSIX- 
compliant mode will have the following access: 
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Functions that take only a directory name as input (such as chdir and 
opendir) will return an error (ENOEXIST). 


Functions whose input is a non-directory file (such as open) will act on the 
non-directory file. 


Functions whose input can be either a file or a directory (such as stat) will 
act on the non-directory file. 
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e readdir will return entries for both the file and the directory. 


12.3.5.3 | POSIX Security Behavior for File Deletion 


The OpenVMS C RTL library follows traditional OpenVMS security rules for 
permitting the deletion or unlinking of files and uses the protection on the files 
or links, whereas the POSIX security behavior for deleting files is to follow the 
security settings for the parent directory of the files or links. 


To get the POSIX security behavior, files in a directory must have an Access 
Control Entry (ACE) placed on them that always grants delete access to those 
files by the class of users or programs that you want to have this behavior. You 
may also want to create a default protection ACE on the parent directory so 
newly created files get the desired behavior. 


Please consult the HP OpenVMS Guide to System Security for more information 
on how to manage Access Control Entries. 


12.4 RMS Interface 


12.4.1 RMS Input/Output of POSIX Pathnames 


As previously described, a quoted pathname is a POSIX pathname prefixed with 
the tag string “UP* and enclosed with opening and closing quotation marks. 

In addition, any quotation marks present in the POSIX pathname need to be 
doubled, consistent with the way DCL handles quoted strings. 


Quoted pathnames are allowed in the primary name, default name, and/or 
related names. By identifying the “UP* prefix and the opening and closing 
quotation marks, RMS interprets the rest of the characters as a standard POSIX 
pathname (with the exception that every pair of quotation marks in the pathname 
is treated as a single quotation mark). If RMS detects a quoted pathname, then 
the expanded and resultant file specifications are supplied by RMS as quoted 
pathnames as well. 


The components of the returned quoted pathname are referenced by the NAM or 
NAML as follows: 


e The node is NULL 
e The dev is "‘UP* 


e The dir consists of all characters between the dev string up to and including 
the final slash (/) 


e The name consists of all characters following the dir up to the final period (.) 
(If there is no final period, the name consists of all characters following the 
dir up to the closing double quote (") ) 


e The type consists of all characters following the name up to the closing double 
quote (") 


e The version is double quote (") 
The dir, name, and type fields can be NUL. 


For example, the quoted pathname "“UP*/a/b.c" consists of the following 
components: 


The node is NUL 
The dev is "*UP*% 
The dir is /a/ 
The name is b 
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The type is .c 
The version is " 


The following RMS routines support symbolic links: 


SYS$OPEN operates on the target file pointed to by the symbolic link. 
SYS$CREATE creates the file pointed to by the symbolic link. 


SYS$PARSE analyzes the file specification string and fills in various NAM 
block fields. 


SYS$SEARCH returns the DVI and FID of the target file. The DID is zero. 
The resultant name is that of the symbolic link and not the target file. 


Setting NAML$V_OPEN_SPECIAL causes SYS$OPEN and SYS$SEARCH to 
not follow the symbolic link. 


The following restrictions apply to RMS processing of POSIX pathnames: 


If the primary file specification is a quoted pathname, then SYS$SEARCH 
returns only one file; in pathnames, no characters are defined as being 
wildcards. 


If the primary file specification is a quoted pathname, then the default and 
related specifications are ignored. 


If the primary file specification is a traditional OpenVMS file specification, 
then the default specification can be a quoted pathname; however, only the 
file name and type are used from the default specification. 


12.4.2 Application Control of RMS Symbolic Link Processing 


Applications, including DCL commands and utilities, need the ability to control 
RMS behavior when RMS encounters symbolic links during typical file operations. 
Specifically, applications need to be able to specify whether or not a pathname 
stored in a symbolic link should be included as part of pathname processing and 
directory searches. Furthermore, applications need to be able to specify different 
behavior depending on how the symbolic link is encountered. 


A NAML$L_INPUT_FLAGS flag is now provided to allow necessary application 
flexibility: 


If SYS$OPEN is supplied a pathname that is a symbolic link, the default 
behavior is to open the file specified by the pathname stored in the symbolic 
link. If the flag NAML$V_OPEN_SPECIAL is set, then the symbolic link file 
itself is opened. 


If the result of a call to SYS$SEARCH is a symbolic link and the flag 
NAML$V_OPEN_SPECIAL is set, the DVI/FID of the symbolic link itself 

is returned. Otherwise, the default behavior is that the DVI/FID of the file 
specified by the pathname stored in the symbolic link is returned, unless that 
pathname is also a symbolic link, in which case the process is repeated until 
a non-symbolic link is reached before returning the DVI/FID. 


When SYS$SEARCH performs wildcard directory lookups, then any symbolic 
links encountered are not examined to determine if they refer to directories. 
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12.5 Defining the POSIX Root 


For absolute POSIX pathnames, RMS needs to interpret the leading ’/’ as a 
UNIX-style root. POSIX expects that everything starts from this POSIX root. 
The POSIX root can be established with the GNV installation procedure or with 
the new DCL command, SET ROOT. 


12.5.1 Suggested Placement of the POSIX Root 


During the GNV installation and configuration procedure or when using the 
SET ROOT command, you need to provide a location for the POSIX root for the 
system. By default, the GNV installation establishes the location of the root 
at SYS$SYSDEVICE:[PSX$ROOT]. You can accept this directory as the root or 
specify another directory. GNV then optionally creates a mount point in "/mnt" 
(which is directory "mnt" in your POSIX root directory) for each disk device on 
your system. 


If you accept the default for the root, or specify any other directory that is not 
the top-level directory of a device, then files that do not reside in the directory 
tree under the root directory will be inaccessible using a POSIX pathname, unless 
the device containing the root directory is mounted by means of a mount point 
under the root. (This mount point is optionally generated by GNV during the 
configuration.) Be aware, though, that when such a mount point is created, 
directory tree traversals can result in a loop. See Figure 12-1. 


Figure 12-1 POSIX Root Placement 
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An alternative is to specify the top-level directory, the Master File Directory 
(MFD), of a device as the root and not create a mount point for that device. This 
makes all of the files on the device accessible via POSIX pathnames. However, 
using the MFD of a device (especially the system device) as the root means that 
all of the files in the MFD are visible when a user displays the files in a root 
directory (such as "Is /"). GNV users will see OpenVMS files that they might not 
expect to see; similarly, DCL users will see UNIX files they might not expect to 
see. Also, the MFD of a device might not be accessible to most general users, 
resulting in unexpected failures. 


We recommend you use the supplied default root directory. 


For more information on mount points, see Section 12.7. 
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12.5.2 The SET ROOT Command 
The SET ROOT command has the following format: 
SET ROOT device-name:directory-spec 


This command defines the POSIX root. In POSIX pathname processing mode, 
RMS and the C RTL will treat the leading ’/’ of a pathname as referring to the 
defined root. By default, the root is SYS$SYSDEVICE:[PSX$ROOT]. 


The root definition does not persist across a reboot. 
The SET ROOT command has the following qualifier: 
/LOG (default) 

/NOLOG 


Controls whether the SET ROOT command displays a success indication after the 
root definition is set. 


12.5.3 The SHOW ROOT Command 


The SHOW ROOT command displays the current value of the system root and, if 
defined, the process root. 


This command has the following format: 


SHOW ROOT 


12.6 Current Working Directory 


On UNIX systems, the current working directory is a directory that is used in 
pathname resolution for pathnames that do not begin with a slash. 


If RMS encounters a symbolic link, the directory in which the symbolic link is 
found is the current working directory for the purposes of pathname resolution. 


For the resolution of POSIX pathnames passed directly to RMS, the current 
working directory is the current OpenVMS default directory for the process. 

If the OpenVMS default directory is not a single directory (for example, the 
directory specification includes a search list), then the current working directory 
is the first directory encountered through the search list. 


12.7 Establishing Mount Points 


Two new utilities, mmt and umnt provide a way for a user to mount and dismount 
file systems from mount points. Only users who have CMKRNL privilege can 
mount and dismount file systems. These utilities are shipped as part of GNV. 


The utilities maintain their own logical name table of mount points, which is 
used to display currently available mount points upon request. 


The interfaces for these utilities are as follows: 


mnt 


List existing mount points. 


mnt file_system mount_point 


Mount file system file_system on mount point mount_point. 


umnt mount_point 


Unmount the file system mounted on mount point mownt_point. 
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12.8 NFS 


12.9 DCL 


umnt file_system 


Unmount the file system file_system from its mount point. 


umnt -A 
Unmount all file systems from their mount points. 


Note that both OpenVMS file specifications and POSIX pathnames are allowed 
for the arguments. 


In TCP/IP Services for OpenVMS, Version 5.4 and older, there was limited 
symbolic link support in the NFS client for the purpose of backing up symbolic 
links from a UNIX server into an OpenVMS saveset and correctly restoring them. 
The client used an application ACE to flag a file as a symbolic link. In Version 
5.5, the client preserves this behavior for an ODS-2 mount. For an ODS-5 mount, 
it creates a symbolic link when it sees the application ACE. This allows savesets 
created with older versions of the client to still be restored with newer versions. 


OpenVMS DCL commands and utilities behave in predictable ways when 
encountering symbolic links. Usually, the symbolic link is followed; for example, 
if symbolic link LINKFILE.TXT points to file TEXT.TXT, then entering the 
command "type LINKFILE.TXT" displays the text contained in TEXT. TXT. 


The symbolic link is followed even if the symbolic link itself is not directly 
specified; for example, if a symbolic link that references a directory is encountered 
when processing a command such as "dir [...]*.TXT", any files with a type of 

" TXT" that exist in the pointed-to directory (and its subdirectories) would 

be displayed. (Note: For OpenVMS Version 8.3, during directory wildcard 
operations, symbolic links are not examined to see if they refer to directories.) 


There are some cases, however, where the symbolic link should not be followed by 
default. Also, it is sometimes desirable to give the user the option of whether or 
not to follow a symbolic link. 


The following commands either do not follow the symbolic link by default and/or 
provide an option whether or not to follow a symbolic link. 


BACKUP 


When a symbolic link is encountered during a backup operation, the symbolic 
link itself is copied. This is true for all backup types—physical, image and 
file. 


COPY 


/SYMLINK 
/NOSYMLINK (default) 


If an input file is a symbolic link, the file referred to by the symbolic link is 
the file that is copied. 


The /SYMLINK qualifier indicates that any input symbolic link is copied. 


CREATE 
/SYMLINK="text" 
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Creates a symbolic link containing the specified text without the enclosing 
quotation marks. 


If the created symbolic link is subsequently encountered during any filename 
processing, the contents of the symbolic link are read and treated as a POSIX 
pathname specification. 


No previous version of the symbolic link can exist. 


DELETE 


If an input file specification parameter is a symbolic link, the symbolic link 
itself is deleted. 


DIRECTORY 


/SYMLINK (default) 
/NOSYMLINK 


If an input file specification parameter is a symbolic link, the displayed 
file attributes are those of the symbolic link itself. If any file attribute is 
requested, then the contents of the symbolic link are also displayed with 
an arrow appearing between the filename and the contents (for example, 
LINK.TXT -> FILE.TXT). 


The /NOSYMLINK qualifier indicates that if an input file specification is a 
symbolic link, then the file attributes of the file to which the symbolic link 
refers are displayed; the displayed name is still the name of the symbolic link 
itself. 


DUMP 


/SYMLINK 
/NOSYMLINK (default) 


If an input file is a symbolic link, the file referred to by the symbolic link is 
the file that is dumped. 


The /SYMLINK qualifier indicates that any input symbolic link is dumped. 


PURGE 


If an input file specification is a symbolic link, the symbolic link itself is 
purged. Because only one version of a symbolic link can exist, this command 
has no effect on that file. 


RENAME 


If an input file specification is a symbolic link, the symbolic link itself is 
renamed. 


If the output file specification is a symbolic link, the operation fails. 


SET FILE 


/SYMLINK 
/NOSYMLINK (default) 


If an input file is a symbolic link, the file referred to by the symbolic link is 
the file that is set. 


The /SYMLINK qualifier indicates that the symbolic link itself is set. 
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Notes 


e The /EXCLUDE qualifier excludes symbolic links that match the 
qualifer’s file specification of files to be excluded. The filename of a 
file that is referred to by a symbolic link is not excluded on the basis 
of its own name. 


Example: 


If symbolic link LINK.TXT refers to TEXT.TXT in another directory, 
then: 


/EXCLUDE=LINK.TXT would exclude LINK.TXT (and, therefore, 
TEXT.TXT) from the operation. 


/EXCLUDE=TEXT.TXT would not exclude LINK.TXT or 
TEXT.TXT from the operation. 


e¢ Given a symbolic link, FSFILE_ATTRIBUTES acts on the file to 
which the symbolic link refers. A new lexical function, FSSYMLINK_ 
ATTRIBUTES, returns information on the symbolic link itself. New 
lexical function FSREADLINK returns the text contents of a symbolic 
link, and NULL if the input is not a symbolic link. 


e Some compilers and utilities will accept quoted pathnames as input 
file specifications and as arguments to qualifiers. These include the 
C and C++ compilers, CXXLINK, the Linker, and the Librarian. 
Linker option files can also contain quoted pathnames. Note that 
the /INCLUDE_DIRECTORY qualifier for the compilers continues 
to accept standard POSIX pathnames rather than the quoted 
pathnames. The Java compiler also continues to accept standard 
POSIX pathnames. In addition, SET DEFAULT accepts quoted 
pathnames as input. 


12.10 GNV 


GNV is the mechanism by which the Open Group utilities are provided on 
OpenVMS systems. GNV is an open source project with updates released on the 
Sourceforge web site. GNV is also available on the OpenVMS Open Source CD. 


Because GNV relies on the C RTL for all file access, no modifications are 

made to GNV for its provided utilities to behave as defined by the Open Group 
specification for symbolic links. To make use of the new symbolic-link and 
POSIX pathname support features, users should set the C RTL DECC$POSIX_ 
COMPLIANT_PATHNAMES feature logical appropriately, before invoking BASH. 


12.11 Restrictions 
The following are known restrictions with symbolic link support: 


e SET FILE/REMOVE on a symbolic link silently fails. 


When SET FILE/REMOVE is executed on a symbolic link, the link is not 
removed. No error is displayed. 


e Coding consideration with RMS and symbolic links: 
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With the introduction of symbolic links and POSIX pathname processing, 
the device name that occurs in a file specification may be different from the 
device on which the file exists. The NAM$T_DVI returned by SYS$PARSE 
/SYS$SEARCH properly identifies the device on which the file resides. 
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Reference Section 


This section describes the functions contained in the HP C Run-Time Library 
(RTL), listed alphabetically. 


aGA4l (ipna, 164) 


a64l (Alpha, 64) 


Converts a character string to a long integer. 


Format 
#include <stdlib.h> 


long a64! (const char *s); 


Argument 


s 
Pointer to the character string that is to be converted to a long integer. 


Description 


The a641 and 164a functions are used to maintain numbers stored in base-64 
ASCII characters as follows: 


e aé641 converts a character string to a long integer. 
e 164a converts a long integer to a character string. 


Each character used for storing a long integer represents a numeric value from 0 
through 63. Up to six characters can be used to represent a long integer. 


The characters are translated as follows: 

e A period (.) represents 0. 

e Aslash (/) represents 1. 

e The numbers 0 through 9 represent 2 through 11. 

e Uppercase letters A through Z represent 12 through 37. 
e Lowercase letters a through z represent 38 through 63. 


The a641 function takes a pointer to a base-64 representation, in which the first 
digit is the least significant, and returns a corresponding long value. If the string 
pointed to by the s parameter exceeds six characters, a641 uses only the first six 
characters. 


If the first six characters of the string contain a null terminator, a641 uses only 
characters preceding the null terminator. 


The a641 function translates a character string from left to right with the least 
significant number on the left, decoding each character as a 6-bit base-64 number. 


If s is the NULL pointer or if the string pointed to by s was not generated by a 
previous call to 164a, the behavior of a641 is unspecified. 


See also 164a. 


REF-3 


aGA4l alpha, 164) 


Return Values 


n Upon successful completion, the long value 
resulting from conversion of the input string. 


OL Indicates that the string pointed to by s is an 
empty string. 
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abort 


abort 


Sends the signal SIGABRT that terminates execution of the program. 


Format 
#include <stdlib.h> 


void abort (void); 
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abs 


abs 

Returns the absolute value of an integer. 
Format 

#include <stdlib.h> 

int abs (int x); 
Argument 

x 

An integer. 


Return Value 


x The absolute value of the input argument. If the 
argument is LONG_MIN, abs returns LONG_ 
MIN because -LONG_MIN cannot fit in an int 
variable. 
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access 


access 
Checks a file to see whether a specified access mode is allowed. 
Note 
The access function does not accept network files as arguments. 
Format 
#include <unistd.h> 
int access (const char “file_spec, int mode); 
Arguments 
file_spec 
A character string that gives an OpenVMS or UNIX style file specification. The 
usual defaults and logical name translations are applied to the file specification. 
mode 
Interpreted as shown in Table REF-1. 
Table REF-1 Interpretation of the mode Argument 
Mode Argument Access Mode 
F_OK Tests to see if the file exists 
X_OK Execute 
W_OK Write (implies delete access) 
R_OK Read 
Combinations of access modes are indicated by ORing the values. For example, to 
check to see if a file has RWED access mode, invoke access as follows: 
access (file spec, R_OK | WOK | X OK); 
Description 


The access function checks a file to see whether a specified access mode is 
allowed. If the DECC$ACL_ACCESS_CHECK feature logical is enabled, this 
function checks OpenVMS Access Control Lists (ACLs) as well as the UIC 
protection. 


Return Values 


0 Indicates that the access is allowed. 
—1 Indicates that the access is not allowed. 
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access 


Example 


#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 


main () 


{ 
if (access ("sys$login:login.com", F_OK)) { 
perror ("ACCESS - FAILED") ; 
exit (2); 
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acos 


acos 


Format 


Argument 


Description 


Returns the arc cosine of its argument. 


#include <math.h> 

double acos (double x); 

float acosf (float x); (Alpha, 164) 

long double acos! (long double x); (Alpha, 164) 
double acosd (double x); (Alpha, 164) 

float acosdf (float x); (Alpha, 164) 


long double acosdl (long double x); (Alpha, 164) 


x 
A radian expressed as a real value in the domain [—1,1]. 


The acos functions compute the principal value of the arc cosine of x in the range 
[0,7] radians for x in the domain [—1,1]. 


The acosd functions compute the principal value of the arc cosine of x in the 
range [0,180] degrees for x in the domain [—1,1]. 


For abs(x) > 1, the value of acos(x) is 0, and errno is set to EDOM. 
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acosh (alpha, 164) 


acosh (Alpha, 164) 


Returns the hyperbolic arc cosine of its argument. 


Format 

#include <math.h> 

double acosh (double x); 

float acoshf (float x); 

long double acoshl (long double x); 
Argument 

x 

A radian expressed as a real value in the domain [1, +Infinity]. 
Description 


The acosh functions return the hyperbolic arc cosine of x for x in the domain [1, 
+Infinity], where acosh(«) = In + sqrt(x**2 — 1)). 


The acosh function is the inverse function of cosh where acosh(cosh(x)) = |x|. 


x < 1is an invalid argument. 


REF-10 


[wJaddch 


[w]addch 


Format 


Arguments 


Description 


Add a character to the window at the current position of the cursor. 


#include <curses.h> 
int addch (char ch); 
int waddch (WINDOW ‘win, char ch); 


win 
A pointer to the window. 


ch 

The character to be added. A new-line character (\n) clears the line to the 

end, and moves the cursor to the next line at the same x coordinate. A return 
character (\r) moves the cursor to the beginning of the line on the window. A tab 
character (\t) moves the cursor to the next tabstop within the window. 


When the waddch function is used on a subwindow, it writes the character onto 
the underlying window as well. 


The addch routine performs the same function as waddch, but on the stdscr 
window. 


The cursor is moved after the character is written to the screen. 


Return Values 


OK Indicates success. 


ERR Indicates that writing the character would 
cause the screen to scroll illegally. For more 
information, see the scrollok function. 
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[w]addstr 


[w]addstr 


Add the string pointed to by str to the window at the current position of the 
cursor. 


Format 
#include <curses.h> 
int addstr (char *str); 
int waddstr (WINDOW ‘win, char *str: 


Arguments 
win 
A pointer to the window. 


str 
A pointer to a character string. 


Description 


When the waddstr function is used on a subwindow, the string is written onto the 
underlying window as well. 


The addstr routine performs the same function as waddstr, but on the stdscr 
window. 


The cursor position changes as a result of calling this routine. 


Return Values 


OK Indicates success. 

ERR Indicates that the function causes the screen 
to scroll illegally, but it places as much of the 
string onto the window as possible. For more 
information, see the scrollok function. 
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alarm 


alarm 


Format 


Argument 


Description 


Sends the signal SIGALRM (defined in the <signal.h> header file) to the 
invoking process after the number of seconds indicated by its argument has 
elapsed. 


#include <unistd.h> 
unsigned int alarm (unsigned int seconds); so POSIX-1) 


int alarm (unsigned int seconds); (Compatability) 


seconds 
Has a maximum limit of LONG_MAX seconds. 


Calling the alarm function with a 0 argument cancels any pending alarms. 


Unless it is caught or ignored, the signal generated by alarm terminates the 
process. Successive alarm calls reinitialize the alarm clock. Alarms are not 
stacked. 


Because the clock has a 1-second resolution, the signal may occur up to 1 second 
early. If the SIGALRM signal is caught, resumption of execution may be held up 
due to scheduling delays. 


When the SIGALRM signal is generated, a call to SYS$WAKE is generated 
whether or not the process is hibernating. The pending wake causes the current 
pause() to return immediately (after completing any function that catches the 
SIGALRM). 


Return Value 


n The number of seconds remaining from a 
previous alarm request. 
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asctime, asctime_r 


asctime, asctime_r 


Converts a broken-down time in a tm structure into a 26-character string in the 
following form: 


Sun Sep 16 01:03:52 1984\n\0 
All fields have a constant width. 


Format 
#include <time.h> 
char *asctime (const struct tm *timeptr); 


char *asctime_r (const struct tm *timeptr, char *buffer); (SO POSIX-1) 


Arguments 


timeptr 
A pointer to a structure of type tm, which contains the broken-down time. 


The tm structure is defined in the <time.h> header file, and also shown in 
Table REF—4 in the description of localtime. 


buffer 
A pointer to a character array that is at least 26 bytes long. This array is used to 
store the generated date-and-time string. 


Description 


The asctime and asctime r functions convert the contents of tm into a 
26-character string and returns a pointer to the string. 


The difference between asctime r and asctime is that the former puts the result 
into a user-specified buffer. The latter puts the result into thread-specific static 
memory allocated by the HP C RTL, which can be overwritten by subsequent 
calls to ctime or asctime; you must make a copy if you want to save it. 


On success, asctime returns a pointer to the string; asctime_r returns its second 
argument. On failure, these functions return the NULL pointer. 


See the localtime function for a list of the members in tm. 


Note 


Generally speaking, UTC-based time functions can affect in-memory time- 
zone information, which is processwide data. However, if the system time 
zone remains the same during the execution of the application (which is 
the common case) and the cache of timezone files is enabled (which is the 
default), then the _r variant of the time functions asctime_r, ctime_r, 
gmtime_r and localtime_r, is both thread-safe and AST-reentrant. 


If, however, the system time zone can change during the execution of 

the application or the cache of timezone files is not enabled, then both 
variants of the UTC-based time functions belong to the third class of 

functions, which are neither thread-safe nor AST-reentrant. 
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asctime, asctime_r 


Return Values 


x A pointer to the string, if successful. 
NULL Indicates failure. 
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asin 


asin 


Format 


Argument 


Description 
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Returns the arc sine of its argument. 


#include <math.h> 

double asin (double x); 

float asinf (float x); (Alpha, 164) 

long double asin! (long double x); (Aipha, 164) 
double asind (double x); (Alpha, 164) 

float asindf (float x); (Alpha, 164) 


long double asindl (long double x); (Alpha, 164) 


x 
A radian expressed as a real number in the domain [—1,1]. 


The asin functions compute the principal value of the arc sine of x in the range 
[—x/2, «/2] radians for x in the domain [—1,1]. 


The asind functions compute the principal value of the arc sine of x in the range 
[—90,90] degrees for x in the domain [—1,1]. 


When abs(x) is greater than 1.0, the value of asin(x) is 0, and errno is set to 
EDOM. 


asinh (ipna, 164) 


asinh (Alpha, 164) 


Returns the hyperbolic arc sine of its argument. 


Format 

#include <math.h> 

double asinh (double x): 

float asinhf (float x); 

long double asinhl (long double x); 
Argument 

x 

A radian expressed as a real value in the domain [—Infinity, +Infinity]. 
Description 


The asinh functions return the hyperbolic arc sine of x for x in the domain 
[—-Infinity, +Infinity], where asinh(x) = In(« + sqrt(x**2 + 1)). 


The asinh function is the inverse function of sinh where asinh(sinh(x)) = x. 
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assert 


assert 


Format 


Argument 


Description 


Example 
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Used for implementing run-time diagnostics in programs. 


#include <assert.h> 


void assert (int expression); 


expression 
An expression that has an int type. 


When assert is executed, if expression is false (that is, it evaluates to 0), assert 
writes information about the particular call that failed (including the text of the 
argument, the name of the source file, and the source line number; the latter 
two are, respectively, the values of the preprocessing macros FILE __ and 
__LINE__) to the standard error file in an implementation-defined format. Then, 
it calls the abort function. 


The assert function writes a message in the following form: 
Assertion failed: expression, file aaa, line nnn 
If expression is true (that is, it evaluates to nonzero) or if the signal SIGABRT is 


being ignored, assert returns no value. 


Note 


If a null character (’\0’) is part of the expression being asserted, then only 
the text up to and including the null character is printed, since the null 
character effectively terminates the string being output. 


Compiling with the CC command qualifier /DEFINE=NDEBUG or with the 
preprocessor directive #define NDEBUG ahead of the #include assert statement 
causes the assert function to have no effect. 


#include <stdio.h> 
#include <assert.h> 


main () 


printf("Only this and the assert\n"); 
assert (1 == 2); /* expression is FALSE */ 


/* abort should be called so the printf will not happen. */ 
printf ("FAIL abort did not execute") ; 


atan 


atan 


Format 


Argument 


Description 


#include <math.h> 

double atan (double x); 

float atanf (float x); (Aipha, 164) 

long double atan! (long double x); (Alpha, 164) 
double atand (double x); (Alpha, 164) 

float atandf (float x); (Alpha, 164) 


long double atandl (long double x); (Alpha, 164) 


x 
A radian expressed as a real number. 


The atan functions compute the principal value of the arc tangent of x in the 
range [—7/2, 7/2] radians. 


The atand functions compute the principal value of the arc tangent of x in the 
range [—90,90] degrees. 
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atan2 


atan2 


Format 


Arguments 


Description 
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#include <math.h> 

double atan2 (double y, double x); 

float atan2f (float y, float x); (Alpha, 164) 

long double atan2I (long double y, long double x); (Alpha, 164) 
double atand2 (double y, double x); (Alpha, 164) 

float atand2f (float y, float x); (Alpha, 164) 


long double atand2! (long double y, long double x); (Alpha, 164) 


y 


A radian expressed as a real number. 


Xx 
A radian expressed as a real number. 


The atan2 functions compute the principal value of the arc tangent of y/x in the 
range [—z,z] radians. The sign of atan2 and atan2f is determined by the sign 
of y. The value of atan2(y,x) is computed as follows, where f is the number of 
fraction bits associated with the data type: 


Value of Input Arguments Angle Returned 
x=Oory/x > 2**(f+1) n/2 * (sign y) 

x >0O and y/x <= 2**(f+1) atan(y /x) 

x <0 and y/x <= 2**(f+1) x * (sign y) + atan(y/x) 


The atand2 functions compute the principal value of the arc tangent of y/x in the 
range [—180,180] degrees. The sign of atand2 and atand2f is determined by the 


sign of y. 


The following are invalid arguments for the atan2 and atand2 functions: 


Function Exceptional Argument 
atan2, atan2f, atan21 x=y=0 

atan2, atan2f, atan21 |x| = |y| = Infinity 
atand2, atand2f, atand21l ea =0 

atand2, atand2f, atand21 |x| = |y| = Infinity 


atanh (ina, 164) 


atanh (ipna, 164 


Returns the hyperbolic arc tangent of its argument. 


Format 

#include <math.h> 

double atanh (double x); 

float atanhf (float x); 

long double atanhl (long double x); 
Argument 

x 

A radian expressed as a real value in the domain [—1,1]. 
Description 


The atanh functions return the hyperbolic arc tangent of x. The atanh function is 
the inverse function of tanh where atanh(tanh(x)) = x. 


|x | >1is an invalid argument. 
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atexit 


atexit 

Registers a function that is called without arguments at program termination. 
Format 

#include <stdlib.h> 

int atexit (void (*func) (void)); 
Argument 


func 
A pointer to the function to be registered. 


Return Values 


0 Indicates that the registration has succeeded. 
nonzero Indicates failure. 

Restriction 
The longjmp function cannot be executed from within the handler, because the 
destination address of the longjmp no longer exists. 

Example 


include <stdlib.h> 
include <stdio.h> 


static void hw(void) ; 


ain() 


atexit (hw) ; 


static void hw() 


puts("Hello, world\n") ; 


Running this example produces the following output: 


Hello, world 
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atof 


atof 


Format 


Argument 


Description 


Converts an ASCII character string to a double-precision number. 


#include <stdlib.h> 


double atof (const char *nptr); 


nptr 

A pointer to the character string to be converted to a double-precision number. 
The string is interpreted by the same rules that are used to interpret floating 
constants. 


The string to be converted has the following format: 
[white-spaces]|[+ | -|digits[radix-character][digits][e | E[+ | -Jinteger] 
Where radix-character is defined in the current locale. 
The first unrecognized character ends the conversion. 


This function is equivalent to strtod(nptr, (char**) NULL). 


Return Values 


x The converted value. 


0 Indicates an underflow or the conversion could 
not be performed. The function sets errno to 
ERANGE or EINVAL, respectively. 


+HUGE_VAL Overflow occurred; errno is set to ERANGE. 
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atoi, atol 


atoi, atol 


Format 


Argument 


Description 


Convert strings of ASCII characters to the appropriate numeric values. 


#include <stdlib.h> 
int atoi (const char *nptr); 


long int atol (const char *nptn); 


nptr 
A pointer to the character string to be converted to a numeric value. 


The atoi and atol functions convert the initial portion of a string to its decimal 
int or long int value, respectively. The atoi and atol functions do not account 
for overflows resulting from the conversion. The string to be converted has the 
following format: 


[white-spaces]|+ | -]digits 


The function call atol (str) is equivalent to strtol (str, (char**) NULL, 
10), and the function call atoi (str) is equivalent to (int) strtol (str, 
(char**) NULL, 10), except, in both cases, for the behavior on error. 


Return Value 
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n The converted value. 


atogq, atoll (pha, 164) 


atogq, atoll (aipia, 164) 


Format 


Argument 


Description 


Convert strings of ASCII characters to the appropriate numeric values. atoll is 
a synonym for atoq. 


#include <stdlib.h> 
_int64 atoq (const char *nptn); 


__int64 atoll (const char *nptr); 


npir 
A pointer to the character string to be converted to a numeric value. 


The atog (or atoll) function converts the initial portion of a string to its decimal 
__int64 value. This function does not account for overflows resulting from the 
conversion. The string to be converted has the following format: 

[white-spaces]|[+ | -]digits 


The function call atog (str) is equivalent to strtog (str, (char**)NULL, 10), 
except for the behavior on error. 


Return Value 


n The converted value. 
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basename 


basename 


Format 


Returns the last component of a pathname. 


#include <libgen.h> 


char *basename (char *path); 


Function Variants 


Argument 


Description 


The basename function has variants named basename32 and basenameé4 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


path 
A UNIX style pathname from which the base pathname is extracted. 


The basename function takes the UNIX style pathname pointed to by path and 
returns a pointer to the pathname’s final component, deleting any trailing slash 
(/) characters. 


If path consists entirely of the slash (/) character, the function returns a pointer 
to the string '/". 


If path is a NULL pointer or points to an empty string, the function returns a 
pointer to the string ".". 


The basename function can modify the string pointed to by path. 


Return Values 
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x A pointer to the final component of path. 
"" If path consists entirely of the 7’? character. 


If path is a NULL pointer or points to an empty 
string. 


bcmp 


bcmp 


Format 


Arguments 


Description 


Compares byte strings. 


#include <strings.h> 


void bemp (const void *string1, const void “string2, size_t length); 


string1, string2 
The byte strings to be compared. 


length 
The length (in bytes) of the strings. 


The bemp function compares the byte string in string1 against the byte string in 
string2. 


Unlike the string functions, there is no checking for null bytes. Zero-length 
strings are always identical. 


Note that bcmp is equivalent to memcmp, which is defined by the ANSI C Standard. 
Therefore, using memcmp is recommended for portable programs. 


Return Values 


0 The strings are identical. 
Nonzero The strings are not identical. 
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bcopy 


bcopy 


Format 


Arguments 


Description 
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Copies byte strings. 


#include <strings.h> 


void bcopy (const void *source, void “destination, size_t length); 


source 
Pointer to the source string. 


destination 
Pointer to the destination string. 


length 
The length (in bytes) of the string. 


The bcopy function operates on variable-length strings of bytes. It copies the 
value of the length argument, in bytes, from the string in the source argument to 
the string in the destination argument. 


Unlike the string functions, there is no checking for null bytes. If the length 
argument is 0 (zero), no bytes are copied. 


Note that bcopy is equivalent to memcpy, which is defined by the ANSI C 
Standard. Therefore, using memcpy is recommended for portable programs. 


box 


box 


Format 


Arguments 


Description 


Draws a box around the window using the character vert as the character for 
drawing the vertical lines of the rectangle, and hor for drawing the horizontal 
lines of the rectangle. 


#include <curses.h> 
int box (WINDOW “win, char vert, char hor); 


win 
The address of the window. 


vert 
The character for the vertical edges of the window. 


hor 
The character for the horizontal edges of the window. 


The box function copies boxes drawn on subwindows onto the underlying window. 
Use caution when using functions such as overlay and overwrite with boxed 
subwindows. Such functions copy the box onto the underlying window. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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brk 


brk 


Format 


Argument 


Description 


Determines the lowest virtual address that is not used with the program. 


#include <stdlib.h> 
void *brk (unsigned long int addr); 


addr 
The lowest address, which the function rounds up to the next multiple of the page 
size. This rounded address is called the break address. 


An address that is greater than or equal to the break address and less than the 
stack pointer is considered to be outside the program’s address space. Attempts 
to reference it will cause access violations. 


When a program is executed, the break address is set to the highest location 
defined by the program and data storage areas. Consequently, brk is needed only 
by programs that have growing data areas. 


Return Values 


Restriction 
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n The new break address. 

(void *)(—1) Indicates that the program is requesting too 
much memory. errno and vaxcSerrno are 
updated. 


Unlike other C library implementations, the HP C RTL memory allocation 
functions (such as malloc) do not rely on brk or sbrk to manage the program heap 
space. Consequently, on OpenVMS systems, calling brk or sbrk can interfere with 
memory allocation routines. The brk and sbrk functions are provided only for 
compatibility purposes. 


bsearch 


bsearch 


Format 


Performs a binary search. It searches an array of sorted objects for a specified 
object. 


#include <stdlib.h> 


void *bsearch (const void *key, const void “base, size_t nmemb, size_t size, int (“compar 
(const void *, const void *)); 


Function Variants 


Arguments 


Description 


The bsearch function has variants named bsearch32 and _bsearché4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


key 
A pointer to the object to be sought in the array. This pointer should be of type 
pointer-to-object and cast to type pointer-to-void. 


base 
A pointer to the initial member of the array. This pointer should be of type 
pointer-to-object and cast to type pointer-to-void. 


nmemb 
The number of objects in the array. 


size 
The size of an object, in bytes. 


compar 
A pointer to the comparison function. 


The array must first be sorted in increasing order according to the specified 
comparison function pointed to by compar. 


Two arguments are passed to the comparison function pointed to by compar. The 
two arguments point to the objects being compared. Depending on whether the 
first argument is less than, equal to, or greater than the second argument, the 
comparison function must return an integer less than, equal to, or greater than 0. 


It is not necessary for the comparison function (compar) to compare every byte 
in the array. Therefore, the objects in the array can contain arbitrary data in 
addition to the data being compared. 


Since it is declared as type pointer-to-void, the value returned must be cast or 
assigned into type pointer-to-object. 
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bsearch 


Return Values 


x A pointer to the matching member of the array 
or a null pointer if no match is found. 

NULL Indicates that the key cannot be found in the 
array. 


Example 

#include <stdio.h> 

#include <stdlib.h> 

#define SSIZE 30 

extern int compare(); /* prototype for comparison function */ 


int array[SSIZE] = {30, Ly 29,25. 28, 3, 2hp-4y 26, 5; 
24, 6, 23, 7, 22, 8, 21, 9, 20, 10, 
19, 11, 18, 12, 17, 13, 16, 14, 15, 25}; 


/* This program takes an unsorted array, sorts it using qsort, */ 


/* and then calls bsearch for each element in the array, */ 
/* making sure that bsearch returns the correct element. */ 
main () 
int i; 
int failure = FALSE; 
int *rkey; 
gsort (array, SSIZE, sizeof (array[0]), &compare) ; 


/* search for each element */ 
for (i = 0; i < SSIZE - 1; i++) { 
/* search array element i */ 
rkey = bsearch((array + i), array, SSIZE, 


sizeof (array[0]), &compare) ; 
/* check for successful search */ 
if (Garray[i] != rkey) { 


printf("Not in array, array element %d\n", i); 
failure = TRUE; 
break; 


if (!failure) 
printf("All elements successfully found!\n"); 


/* Simple comparison routine. */ 


/* Returns: = 0 if a ==b */ 
/* <0ifa<b */ 
/* >0ifa>b */ 


int compare(int *a, int *b) 


return (*a - *b); 


This example program outputs the following: 


All elements successfully found! 
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btowc 


btowc 
Converts a one-byte multibyte character to a wide character in the initial shift 
state. 
Format 
#include <wchar.h> 
wint_t btowc (int c); 
Argument 
c 
The character to be converted to a wide-character representation. 
Description 


The btowc function determines whether (unsigned char)c is a valid one-byte 
multibyte character in the initial shift state, and if so, returns a wide-character 
representation of that character. 


Return Values 


x The wide-character representation of unsigned 
char c. 
WEOF Indicates an error. The c argument has the 


value EOF or does not constitute a valid one-byte 
multibyte character in the initial shift state. 
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bzero 


bzero 

Copies null characters into byte strings. 
Format 

#include <strings.h> 

void bzero (void “string, size_t length); 
Arguments 

string 

Specifies the byte string into which you want to copy null characters. 

length 

Specifies the length (in bytes) of the string. 
Description 


The bzero function copies null characters (’\ 0’) into the byte string pointed to by 
string for length bytes. If length is 0 (zero), then no bytes are copied. 
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cabs 


cabs 


Format 


Argument 


Description 


Returns the absolute value of a complex number. 


#include <math.h> 
double cabs (cabs_t 2); 
float cabsf (cabsf_t 2); (Alpha, 164) 


long double cabs! (cabsl_t 2); (Alpha, 164) 


z 
A structure of type cabs_t, cabsf_t, or cabsl_t. These types are defined in the 
<math.h> header file as follows: 


typedef struct {double x,y;} cabs t; 
typedef struct { float x, y; } cabsf_t; (Alpha, 164) 
typedef struct { long double x, y; } cabsl_t; (Alpha, 164) 


The cabs functions return the absolute value of a complex number by computing 
the Euclidean distance between its two points as the square root of their 
respective squares: 


sqrt(x? + y?) 
On overflow, the return value is undefined. 


The cabs, cabsf, and cabs1 functions are equivalent to the hypot, hypotf, and 
hypot1 functions, respectively. 
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CacOS (Alpha, 164) 


CacCOS (Alpha, 164) 


Returns the complex arc cosine of its argument. 


Format 

#include <complex.h> 

double complex cacos (double complex 2); 

float complex cacosf (float complex 2): 

long double complex cacos! (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The cacos functions compute the complex arc cosine of z, with branch cuts outside 
the interval [—1, +1] along the real axis. 


Return Values 
n The complex arc cosine value, in the range of 
a strip mathematically unbounded along the 


imaginary axis and in the interval [0, 7] along 
the real axis. 
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cacosh dipna, 164) 


CacoSsh ane, 164 


Returns the complex arc hyperbolic cosine of its argument. 


Format 

#include <complex.h> 

double complex cacosh (double complex 2); 

float complex cacoshf (float complex 2); 

long double complex cacoshl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The cacosh functions compute the complex arc hyperbolic cosine of z, with a 
branch cut at values less than 1 along the real axis. 


Return Values 
n The complex arc hyperbolic cosine value, in the 
range of a half-strip of non-negative values along 


the real axis and in the interval [—iz, +iz] along 
the imaginary axis. 
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calloc 


calloc 


Allocates an area of zeroed memory. This function is AST-reentrant. 


Format 
#include <stdlib.h> 


void *calloc (size_t number, size_t size); 


Function Variants 
The calloc function has variants named calloc32 and _callocé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 

Arguments 


number 
The number of items to be allocated. 


size 


The size of each item. 


Description 
The calloc function initializes the items to 0. 


See also malloc and realloc. 


Return Values 


x The address of the first byte, which is aligned on 
a quadword boundary (Alpha only) or an octaword 
boundary (164 only) . 


NULL Indicates an inability to allocate the space. 
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Carg (Alpha, 164) 


Carg alpha, 164) 


Returns the phase angle of its complex argument. 


Format 

#include <complex.h> 

double carg (double complex 2); 

float cargf (float complex 2); 

long double cargl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The carg functions compute the argument (also called phase angle) of z, with a 
branch cut along the negative real axis. 


Return Values 


n The value of the argument of z, in the interval 
[-x, +7]. 
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CaSiN (Alpha, 164) 


CaSIN ipha, 164) 


Returns the complex arc sine of its argument. 


Format 

#include <complex.h> 

double complex casin (double complex 2); 

float complex casinf (float complex 2); 

long double complex casinl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The casin functions compute the complex arc sine of z, with branch cuts outside 
the interval [—1, +1] along the real axis. 


Return Values 
n The complex arc sine value, in the range of 
a strip mathematically unbounded along the 


imaginary axis and in the interval [—7/2, +2/2] 
along the real axis. 
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casinh (ipna, 164 


cas i n h (Alpha, 164) 


Returns the complex arc hyperbolic sine of its argument. 


Format 

#include <complex.h> 

double complex casinh (double complex 2); 

float complex casinhf (float complex 2); 

long double complex casinhl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The casinh functions compute the complex arc hyperbolic sine of z, with branch 
cuts outside the interval [—i, +i] along the imaginary axis. 


Return Values 
n The complex arc hyperbolic sine value, in the 
range of a strip mathematically unbounded along 


the real axis and in the interval [—iz/2, +iz/2] 
along the imaginary axis. 
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catan (alpha, 164) 


catan (Alpha, 164) 


Returns the complex arc tangent of its argument. 


Format 

#include <complex.h> 

double complex catan (double complex 2): 

float complex catanf (float complex 2); 

long double complex catanl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The catan functions compute the complex arc tangent of z, with branch cuts 
outside the interval [—i, +i] along the imaginary axis. 


Return Values 
n The complex arc tangent value, in the range 
of a strip mathematically unbounded along the 


imaginary axis and in the interval [—7/2, +z/2] 
along the real axis. 
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catanh (@ipna, 164) 


catanh apna, 164 


Returns the complex arc hyperbolic tangent of its argument. 


Format 

#include <complex.h> 

double complex catanh (double complex 2); 

float complex catanhf (float complex 2); 

long double complex catanhl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The catanh functions compute the complex arc hyperbolic tangent of z, with 
branch cuts outside the interval [—1, +1] along the imaginary axis. 


Return Values 
n The complex arc hyperbolic tangent value, in the 
range of a strip mathematically unbounded along 


the real axis and in the interval [—iz/2, +iz/2] 
along the imaginary axis. 
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catclose 


catclose 


Format 


Argument 


Description 


Closes a message catalog. 


#include <nl_types.h> 


int catclose (nl_catd cata); 


catd 
A message catalog descriptor. This is returned by a successful call to catopen. 


The catclose function closes the message catalog referenced by catd and frees 
the catalog file descriptor. 


Return Values 
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0 Indicates that the catalog was successfully closed. 
—1 Indicates that an error occurred. The function 
sets errno to the following value: 


e EBADF - The catalog descriptor is not valid. 


catgets 


catgets 


Format 


Retrieves a message from a message catalog. 


#include <nl_types.h> 


char *catgets (nl_catd catd, int set_id, int msg_id, const char “s); 


Function Variants 


Arguments 


Description 


The catgets function has variants named catgets32 and _catgetsé64 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


catd 
A message catalog descriptor. This is returned by a successful call to catopen. 


set_id 
An integer set identifier. 


msg_id 
An integer message identifier. 


s 
A pointer to a default message string that is returned by the function if the 
message cannot be retrieved. 


The catgets function retrieves a message identified by set_id and msg_id, in the 
message catalog catd. The message is stored in a message buffer in the nl_catd 
structure, which is overwritten by subsequent calls to catgets. If a message string 
needs to be preserved, it should be copied to another location by the program. 


Return Values 


x Pointer to the retrieved message. 
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catgets 


s Pointer to the default message string. Indicates 
that the function is not able to retrieve the 
requested message from the catalog. This 
condition can arise if the requested pair (set_d, 
msg_id) does not represent an existing message 
from the open catalog, or it indicates that an 
error occurred. If an error occurred, the function 
sets errno to one of the following values: 


e EBADF - The catalog descriptor is not valid. 


e EVMSRR — An OpenVMS I/O read error; 
the OpenVMS error code can be found in 
vaxcSerrno. 


Example 


#include <nl_types.h> 
#include <locale.h 
#include <stdarg.h 
#include <stdio.h> 
#include <stdlib.h 
#include <unixio.h> 


Vv 


Vv 


/* This test makes use of all the message catalog routines. catopen */ 


/* opens the catalog ready for reading, then each of the three */ 
/* messages in the catalog are extracted in turn using catgets and */ 
/* printed out. catclose closes the catalog after use. */ 


/* The catalog source file used to create the catalog is as follows: */ 
/* $ This is a message file 


uae 

* Squote " 

* § another comment line 

* Sset 1 

* 1 "First set, first message" 

* 2 "second message - This long message uses a backslash \ 

* for continuation." 

* Sset 2 

* 1 "Second set, first message" */ 


char *default_msg = "this is the first message."; 


main () 


{ 


nl_catd catalog; 
int msgl, 
msg2, 
retval; 


char *cat = "sys$disk: []catgets_example.cat"; /*Force local catalog*/ 
char *msgtxt; 

char string[128] ; 

/* Create the message test catalog */ 

system("gencat catgets example.msgx catgets example.cat") ; 


if ((catalog = catopen(cat, 0)) == (nl_catd) - 1) { 
perror ("catopen") ; 
exit (EXIT FAILURE) ; 


msgtxt = catgets(catalog, 1, 1, default_msg) ; 
printf ("%s\n", msgtxt) ; 
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catgets 


msgtxt = catgets(catalog, 1, 2, default_msq) ; 
printf ("%s\n", msgtxt) ; 


msgtxt = catgets(catalog, 2, 1, default_msqg) ; 
printf ("%s\n", msgtxt) ; 


if ((retval = catclose(catalog)) == -1) { 
perror ("catclose") ; 
exit (EXIT_FAILURE) ; 


delete("catgets example.cat;") ; /* Remove the test catalog */ 


Running the example program produces the following result: 


First set, first message 

second message - This long message uses a backslash for 
continuation. 

Second set, first message 
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catopen 


catopen 


Format 


Arguments 


Description 
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Opens a message catalog. 


#include <nl_types.h> 


nl_catd catopen (const char *name, int oflag); 


name 
The name of the message catalog to open. 


oflag 

An object of type int that determines whether the locale set for the 
LC_MESSAGES category in the current program’s locale or the logical name 
LANG is used to search for the catalog file. 


The catopen function opens the message catalog identified by name. 


If name contains a colon (:), a square opening bracket ([), or an angle bracket 
(<), or is defined as a logical name, then it is assumed that name is the complete 
file specification of the catalog. 


If it does not include these characters, catopen assumes that name is a logical 
name pointing to an existing catalog file. If name is not a logical name, then 

the logical name NLSPATH is used to define the file specification of the message 
catalog. NLSPATH is defined in the user’s process. If the NLSPATH logical name 
is not defined, or no message catalog can be opened in any of the components 
specified by the NLSPATH, then the SYS$NLSPATH logical name is used to 
search for a message catalog file. 


Both NLSPATH and SYS$NLSPATH are comma-separated lists of templates. 
The catopen function uses each template to construct a file specification. For 
example, NLSPATH could be defined as: 


DEFINE NLSPATH SYSS$SYSROOT: [SYS$I118N.MSG] SN.CAT, SYSSCOMMON: [SYSMSG] SN. CAT 


In this example, catopen first searches the directory 
SYS$SYSROOT:[SYS$I18N.MSG] for the named catalog. If the named catalog is 
not found there, the directory SYS$COMMON:|[SYSMSG] is searced. The catalog 
name is constructed by substituting %N with the name passed to catopen, 

and adding the .cat suffix. %N is known as a substitution field. The following 
substitution fields are valid: 


Field Meaning 


JN Substitute the name passed to catopen 


catopen 


Field Meaning 


%L 1 Substitute the locale name. 


The period (.) and at-sign (@) characters in the locale name are 
replaced by an underscore (_) character. 


For example, the "zh_CN.dechanzi@radical" locale name results in a 
substitution of ZH_CN_DECHANZI_RADICAL. 

%| 1 Substitute the language part of the locale name. For example, the 
language part of the en_GB.ISO8859-1 locale name is en. 


Jot 1 Substitute the territory part of the locale name. For example, the 
territory part of the en_GB.ISO8859-1 locale is GB. 
Yoo 1 Substitute the codeset name from the locale name. For example, the 


codeset name of the en_GB.ISO8859-1 locale name is ISO8859-1. 


1This substitution assumes that the locale name is of the form language_territory.codeset@mode 


If the oflag argument is set to NL_CAT_LOCALEH, then the current locale as 
defined for the LC_MESSAGES category is used to determine the substitution 
for the %L, %l, %t, and %c substitution fields. If the oflag argument is set to 0, 
then the value of the LANG environment variable is used as a locale name to 
determine the substitution for these fields. Note that using NL_CAT_LOCALE 
conforms to the XPG4 specification while a value of 0 (zero) exists for the purpose 
of preserving XPG3 compatibility. Note also, that catopen uses the value of the 
LANG environment variable without checking whether the program’s locale can 
be set using this value. That is, catopen does not check whether this value can 
serve as a valid locale argument in the setlocale call. 


If the substitution value is not defined, an empty string is substituted. 


A leading comma or two adjacent commas (,,) is equivalent to specifying %N. For 
example, 


DEFINE NLSPATH ",%N.CAT,SYSSCOMMON: [SYSMSG.%L] SN.CAT" 

In this example, catopen searches in the following locations in the order shown: 
1. name (in the current directory) 

2. name.cat (in the current directory) 


3. SYS$COMMON:[SYSMSG._locale_name|name.cat 


Return Values 
x A message catalog file descriptor. Indicates the 


call was successful. This descriptor is used in 
calls to catgets and catclose. 
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catopen 
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(nl_catd) —1 


Indicates an error occurred. The function sets 
errno to one of the following values: 


e EACCES - Insufficient privilege or file 
protection violation, or file currently locked 
by another user. 


e EMFILE — Process channel count exceeded. 


e ENAMETOOLONG - The full file 
specification for message catalog is too long 


e ENOENT — Unable to find the requested 
message catalog. 


e ENOMEM - Insufficient memory available. 


e ENOTDIR - Part of the name argument is 
not a valid directory. 


e EVMSERR - An error occurred that does not 
match any errno value. Check the value of 
vaxcSerrno. 


ecbrt (ipna, 164) 


Chrt apna, 1649 


Format 


Argument 


Returns the rounded cube root of y. 


#include <math.h> 

double cbrt (double y); 

float cbrtf (float y); 

long double cbrtl (long double y); 


A real number. 
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CCOS (Alpha, 164) 


CCOS (alpha, 164) 


Returns the complex cosine of its argument. 


Format 

#include <complex.h> 

double complex ccos (double complex 2): 

float complex ccosf (float complex 2); 

long double complex ccos! (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The ccos functions return the complex cosine of z. 
Return Values 


x The complex cosine value. 
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CCOSN (Alpha, 164) 


CCOSHA apna, 164 


Returns the complex hyperbolic cosine of its argument. 


Format 

#include <complex.h> 

double complex ccosh (double complex 2); 

float complex ccoshf (float complex 2); 

long double complex ccoshl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The ccosh functions return the complex hyperbolic cosine of z. 
Return Values 


x The complex hyperbolic cosine value. 
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ceil 


ceil 

Returns the smallest integer that is greater than or equal to its argument. 
Format 

#include <math.h> 

double ceil (double x); 

float ceilf (float x); (Alpha, 164) 

long double ceill (long double x); (Alpha, 164) 
Argument 


4 
A real value. 


Return Value 


n The smallest integer greater than or equal to the 
function argument. 
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C@XP (Alpha, 164) 


CEXP pha, 164) 


Returns the complex exponent of its argument. 


Format 

#include <complex.h> 

double complex cexp (double complex 2); 

float complex cexpf (float complex 2); 

long double complex cexpl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The cexp functions compute the complex exponential value of z, defined as e**z, 
where e is the constant used as a base for natural logarithms. 


Return Values 


x The complex exponential value of the argument. 
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cfree 


cfree 


Format 


Argument 


Description 
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Makes available for reallocation the area allocated by a previous calloc, malloc, 
or realloc call. This function is AST-reentrant. 


#include <stdlib.h> 
void cfree (void *ptr); 


pir 
The address returned by a previous call to malloc, calloc, or realloc. 


The contents of the deallocated area are unchanged. 


In HP C for OpenVMS Systems, the free and cfree functions are equivalent. 
Some other C implementations use free with malloc or realloc, and cfree with 
calloc. However, since the ANSI C standard does not include cfree, using free 
may be preferable. 


See also free. 


chdir 


chdir 


Format 


Arguments 


Description 


Changes the default directory. 


#include <unistd.h> 
int chdir (const char *dir_spec); SO POSIX-1) 


int chdir (const char *dir_spec, ... ); (HP C Extension) 


dir_spec 
A null-terminated character string naming a directory in either an OpenVMS or 
UNIX style specification. 


This argument is an HP C extension available when not defining any of the 
standards-related feature-test macros (see Section 1.5) and not compiling in strict 
ANSI C mode (/STANDARD=ANSI89). The argument is an optional flag of type 
int that is significant only when calling chdir from USER mode. 


If the value of the flag is 1, the new directory is effective across images. If the 
value is not 1, the original default directory is restored when the image exits. 


The chdir function changes the default directory. The change can be permanent 
or temporary. Permanent means that the new directory remains as the default 
directory after the image exits. Temporary means that on image exit, the default 
is set to whatever it was before the execution of the image. 


There are two ways of making the change permanent: 
e Call chdir from USER mode with the second argument set to 1. 


e Call chdir from SUPERVISOR or EXECUTIVE mode, regardless of the value 
of the second argument. 


Otherwise, the change is temporary. 


Return Values 


0 Indicates that the directory is successfully 
changed to the given name. 


—1 Indicates that the change attempt has failed. 


REF-57 


chmod 


chmod 


Format 


Arguments 


Description 


Changes the file protection of a file. 


#include <stat.h> 


int chmod (const char *file_spec, mode_t mode): 


file_spec 
The name of an OpenVMS or UNIX style file specification. 


mode 


A file protection. Modes are constructed by performing a bitwise OR on any of the 
values shown in Table REF-2. 


Table REF-2 File Protection Values and Their Meanings 


Value Privilege 

0400 OWNER:READ 
0200 OWNER:WRITE 
0100 OWNER: EXECUTE 
0040 GROUP:READ 
0020 GROUP:WRITE 
0010 GROUP: EXECUTE 
0004 WORLD:READ 
0002 WORLD: WRITE 
0001 WORLD: EXECUTE 


When you supply a mode value of 0, the chmod function gives the file the user’s 
default file protection. 


The system is given the same privileges as the owner. A WRITE privilege also 
implies a DELETE privilege. 


You must have a WRITE privilege for the file specified to change the mode. 


The C RTL does not support the S_ISVTX bit. Setting the S_ISVTX mode has no 
effect. 


Return Values 
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0 Indicates that the mode is successfully changed. 
—1 Indicates that the change attempt has failed. 


chown 


chown 

Changes the user ID and group ID of the specified file. 
Format 

#include <unistd.h> 

int chown (const char *file_spec, uid_t owner, gid_t group); 
Arguments 


file_spec 
The address of an ASCII file name. 


owner 
The new user ID of the file. 


group 
The new group ID of the file. 


Return Values 


0 Indicates success. 
=1 Indicates failure. 
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cimag ipha, 164 


CIMA Alpha, 164 


Returns the imaginary part of its complex argument. 


Format 

#include <complex.h> 

double cimag (double complex 2); 

float cimagf (float complex 2); 

long double cimag! (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The cimag functions return the imaginary part of z as a real number. 
Return Values 


x The imaginary part value. 


REF-60 


[w]clear 


[w]clear 
Erase the contents of the specified window and reset the cursor to coordinates 
(0,0). The clear function acts on the stdscr window. 
Format 
#include <curses.h> 
int clear(); 
int wclear (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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clearerr 


clearerr 
Resets the error and end-of-file indicators for a file (so that ferror and feof will 
not return a nonzero value). 
Format 
#include <stdio.h> 
void clearerr (FILE *file_ptr); 
Argument 


file_ptr 
A file pointer. 
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clearerr_unlocked (ipia, 164) 


clearerr_unlocked «ipa, 164 


Format 


Argument 


Description 


Same as the clearerr function, except used only within a scope protected by 
flockfile and funlockfile. 


#include <stdio.h> 


void clearerr_unlocked (FILE *file_ptr); 


file_ptr 
A file pointer. 


The reentrant version of the clearerr function is locked against multiple threads 
calling it simultaneously. This incurs overhead to ensure integrity of the stream. 
The unlocked version of this call, clearerr_unlocked can be used to avoid the 
overhead. The clearerr_ unlocked macro is functionally identical to the clearerr 
macro, except that it is not required to be implemented in a thread-safe manner. 
The clearerr_ unlocked function can be safely used only within a scope that is 
protected by the flockfile and funlockfile functions used as a pair. The caller 
must ensure that the stream is locked before clearerr_unlocked is used. 


See also flockfile, ftrylockfile, and funlockfile. 
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clearok 


clearok 

Sets the clear flag for the window. 
Format 

#include <curses.h> 

clearok (WINDOW *win, bool bool); 
Arguments 


win 
The entire size of the terminal screen. You can use the windows stdscr and 
curscr with clearok. 


boolf 

A Boolean value of TRUE or FALSE. If the argument is TRUE, this forces a 
clearscreen to be printed on the next call to refresh, or stops the screen from 
being cleared if boolf is FALSE. 


The type bool is defined in the <curses.h> header file as follows: 


#define bool int 


Description 


Unlike the clear function, the clearok function does not alter the contents of 
the window. If the win argument is curscr, the next call to refresh causes a 
clearscreen, even if the window passed to refresh is not a window the size of the 
entire terminal screen. 
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clock 


clock 


Format 


Description 


Determines the CPU time (in 10-millisecond units) used since the beginning of 
the process. The time reported is the sum of the user and system times of the 
calling process and any terminated child processes for which the calling process 
has executed wait or system. 


#include <time.h> 


clock_t clock (void); 


The value returned by the clock function must be divided by the value of the 
CLK_TCK, as defined in the standard header file <time.h>, to obtain the time in 
seconds. 


The type clock _t is defined in the <time.h> header file as follows: 
typedef long int clock t; 


Only the accumulated times for child processes running a C main program or a 
program that calls VAXC$CRTL_INIT or DECC$CRTL_INIT are included. 


A typical usage of the clock function is to call it after a program does its initial 
setup, and then again after the program executes the code to be timed. Then 
subtract the two values to give elapsed CPU time. 


Return Values 


n The processor time used. 


-1 Indicates that the processor time used is not 
available. 
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clock_getres (ipa, 164) 


clock_getres (ipha, 164 


Gets the resolution for the specified clock. 


Format 
#include <time.h> 


int clock_getres (clockid_t clock_id, struct timespec *res); 


Arguments 


clock_id 
The clock type used to obtain the resolution. The CLOCK_REALTIME clock is 
supported and represents the TIME-OF-DAY clock for the system. 


res 
A pointer to the timespec data structure that receives the value of the clock’s 
resolution. 


Description 


The clock_getres function obtains the resolution value for the specified clock. 
Clock resolutions are implementation-dependent and cannot be set by a process. 


If the res argument is not NULL, the resolution of the specified clock is stored in 
the location pointed to by res. 


If res is NULL, the clock resolution is not stored. 


If the time argument (¢p) of clock _settime is not a multiple of res, then the value 
is truncated to a multiple of res. 


On success, the function returns 0. 
On failure, the function returns —1 and sets errno to indicate the error. 


See also clock gettime, clock settime, time, and ctime. 


Return Values 


0 Indicates success. 
—1 Indicates failure; errno is set to the following 
value: 


e EINVAL — The clock_id argument does not 
specify a known clock. 
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clock_gettime (ira, 164 


clock_gettime dipra, 164 


Format 


Arguments 


Description 


Returns the current time (in seconds and nanoseconds) for the specified clock. 


#include <time.h> 


int clock_gettime (clockid_t clock_id, struct timespec *ip); 


clock_id 

The clock type used to obtain the time for the clock that is set. The CLOCK_ 
REALTIME clock is supported and represents the TIME-OF-DAY clock for the 
system. 


tp 
A pointer to a timespec data structure. 


The clock gettime function returns the current tp value for the specified clock, 
clock_id. 


On success, the function returns 0. 
On failure, the function returns —1 and sets errno to indicate the error. 


See also clock getres, clock settime, time, and ctime. 


Return Values 


0 Indicates success. 
-1 Indicates failure; errno is set to the following 
value: 


e EINVAL — The clock_id argument does not 
specify a known clock, or the tp argument 
specifies a nanosecond value less than 0 or 
greater than or equal to 1 billion. 
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clock_settime (pia, 164) 


clock_settime ayia, 16 


Format 


Arguments 


Description 


Sets the specified clock. 


#include <time.h> 


int clock_settime (clockid_t clock_id, const struct timespec *ip); 


clock_id 
The clock type used for the clock that is to be set. The CLOCK_REALTIME clock 
is supported and represents the TIME-OF-DAY clock for the system. 


tp 
A pointer to a timespec data structure. 


The clock settime function sets the specified clock, clock_id, to the value 
specified by tp. Time values that are between two consecutive non-negative 
integer multiples of the resolution of the specified clock are truncated down to the 
smaller multiple of the resolution. 


A clock can be systemwide (that is, visible to all processes) or per-process 
(measuring time that is meaningful only within a process). 


The CLOCK_REALTIME clock, defined in <time.h>, represents the realtime 
clock for the system. For this clock, the values specified by clock settime and 
returned by clock gettime represent the amount of time elapsed, in seconds and 
nanoseconds, since the Epoch. The Epoch is defined as 00:00:00:00 January 1, 
1970 Greenwich Mean Time (GMT). 


You must have OPER, LOG_IO, and SYSPRV privileges to use the clock settime 
function. 


On success, the function returns 0. 
On failure, the function returns —1 and sets errno to indicate the error. 


See also clock getres, clock gettime, time, and ctime. 


Return Values 
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0 Indicates success. 


clock_settime «ira, 164 


—1 Indicates failure; errno is set to the following 
value: 


EINVAL — The clock_id argument does not 
specify a known clock, or the tp argument is 
outside the range for the given clock_id or 
specifies a nanosecond value less than 0 or 
greater than or equal to 1 billion. 


EPERM — The requesting process does not 
have the appropriate privilege to set the 
specified clock. 
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Clog Aipha, 164) 


C1OG Alpha, 164) 


Returns the complex natural (base e) logarithm of its argument. 


Format 

#include <complex.h> 

double complex clog (double complex 2); 

float complex clogf (float complex 2); 

long double complex clogl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The clog functions return the complex natural (base e) logarithm of z, with a 
branch cut along the negative real axis. 


Return Values 
x The complex natural logarithm value in the 
range of a strip mathematically unbounded along 


the real axis and in the interval [—iz, +iz] along 
the imaginary axis. 
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close 


close 


Format 


Argument 


Description 


Closes the file associated with a file descriptor. 


#include <unistd.h> 


int close (int file_desc); 


file_desc 
A file descriptor. 


The close function tries to write buffered data by using an implicit call to fflush. 
If the write fails (because the disk is full or the user’s quota was exceeded, for 
example), close continues executing. It closes the OpenVMS channel, deallocates 
any buffers, and releases the memory associated with the file descriptor (or FILE 
pointer). Any buffered data is lost, and the file descriptor (or FILE pointer) no 
longer refers to the file. 


If your program needs to recover from errors when flushing buffered data, it 
should make an explicit call to fsync (or fflush) before calling close. 


Return Values 


Example 


0 Indicates that the file is properly closed. 


—1 Indicates that the file descriptor is undefined 
or an error occurred while the file was being 
closed (for example, if the buffered data cannot 
be written out). 


#include <unistd.h> 
int fd; 


fd = open ("student.dat", 1); 


close (£d) ; 
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closedir 


closedir 


Format 


Argument 


Description 


Example 
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Closes directories. 


#include <dirent.h> 


int closedir (DIR *dir_pointer); 


dir_pointer 
Pointer to the dir structure of an open directory. 


The closedir function closes a directory stream and frees the structure 
associated with the dir_pointer argument. Upon return, the value of dir_pointer 
does not necessarily point to an accessible object of the type DIR. 


The type DIR, which is defined in the <dirent.h> header file, represents a 
directory stream that is an ordered sequence of all the directory entries in a 
particular directory. Directory entries represent files. You can remove files from 
or add files to a directory asynchronously to the operation of the readdir function. 


Note 


An open directory must always be closed with the closedir function to 
ensure that the next attempt to open the directory is successful. 


The following example shows how to search a directory for the entry name, using 
the opendir, readdir, and closedir functions: 

include <dirent.h> 

include <stdio.h> 


include <stdlib.h> 
include <string.h> 


define FOUND 1 
define NOT FOUND 0 


static int dir_example(const char *name, unsigned int unix_style) 


DIR *dir pointer; 
struct dirent *dp; 


if ( unix_style ) 
dir pointer = opendir("."); 
else 
dir pointer = opendir(getenv ("PATH") ) ; 


if ( !dir_ pointer 
perror("opendir") ; 
return NOT FOUND; 


Return Values 


} 


/* Note, that if opendir() was called with UNIX style file 
/* spec like ".", readdir() will return only a single 

/* version of each file in the directory. In this case the 
/* name returned in d_name member of the dirent structure 

/* will contain only file name and file extension fields, 

/* both lowercased like "foo.bar". 


/* If opendir() was called with OpenVMS style file spec, 
/* readdir() will return every version of each file in the 
/* directory. In this case the name returned in d_name 

/* member of the dirent structure will contain file name, 
/* file extension and file version fields. All in upper 

/* case, like "FOO.BAR;1". 


for ( dp = readdir(dir_ pointer) ; 
dp && strcmp (dp->d_name, name) ; 
dp = readdir(dir pointer) ) 


fp 


closedir(dir_ pointer) ; 


if ( dp != NULL ) 
return FOUND; 
else 
return NOT FOUND; 


int main (void) 


char *filename = "foo.bar"; 
FILE *£p; 


remove (filename) ; 


if ( !(fp = fopen(filename, "w")) ) { 
perror("fopen") ; 
return (EXIT FAILURE) ; 


if ( dir_ example ( "FOO.BAR;1", 0 ) == FOUND ) 
puts ("OpenVMS style: found"); 

else 
puts ("OpenVMS style: not found"); 

if ( dir_example( "foo.bar", 1 ) == FOUND ) 
puts ("UNIX style: found"); 

else 


puts ("UNIX style: not found") ; 


fclose (fp) ; 
remove (filename) ; 
return( EXIT SUCCESS ); 


Indicates success. 


closedir 


Indicates an error and is further specified in the 


global errno. 
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[w]clrattr 


[w]clrattr 
Deactivate the video display attribute attr within the window. The clrattr 
function acts on the stdscr window. 
Format 
#include <curses.h> 
int clrattr (int attr); 
int welrattr (WINDOW *win, int attr); 
Arguments 


win 
A pointer to the window. 


attr 

Video display attributes that can be blinking, boldface, reverse video, and 
underlining; they are represented by the defined constants _BLINK, _BOLD, 
_REVERSE, and _UNDERLINE. To clear multiple attributes, separate them with 
a bitwise OR operator ( | ) as follows: 


clrattr( BLINK | _UNDERLINE) ; 


Description 
These functions are specific to HP C for OpenVMS Systems and are not portable. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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[w]cirtobot 


[w]cirtobot 


Erase the contents of the window from the current position of the cursor to the 
bottom of the window. The clrtobot function acts on the stdscr window. 


Format 

#include §<curses.h> 

int clrtobot( ); 

int wclrtobot (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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[w]cirtoeol 


[w]cirtoeol 


Erase the contents of the window from the current cursor position to the end 
of the line on the specified window. The clrtoeol function acts on the stdscr 


window. 
Format 

#include <curses.h> 

int clrtoeol( ); 

int welrtoeol (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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confstr 


confstr 


Format 


Arguments 


Description 


Example 


Determines the current value of a specified system variable defined by a string 
value. 


#include <unistd.h> 


size_t confstr (int name, char “buf, size_t len); 


name 
The system variable setting. Valid values for the name argument are the _CS_X 
names defined in the <unistd.h> header file. 


buf 
Pointer to the buffer where the confstr function copies the name value. 


len 
The size of the buffer storing the name value. 


The confstr function allows an application to determine the current setting of 
certain system parameters, limits, or options that are defined by a string value. 
The function is mainly used by applications to find the system default value for 
the PATH environment variable. 


If the following conditions are true, then the confstr function copies that value 
into a len-byte buffer pointed to by buf: 


e The len argument is not 0 (zero). 
e The name argument has a system-defined value. 
e The buf argument is not a NULL pointer. 


If the returned string is longer than Jen bytes, including the terminating null, 
then the confstr function truncates the string to Jen — 1 bytes and adds a 
terminating null to the result. The application can detect that the string was 
truncated by comparing the value returned by the confstr function with the 
value of the Jen argument. 


The <limits.h> header file contains system-defined limits. The <unistd.h> 
header file contains system-defined environmental variables. 


To find out how big a buffer is needed to store the string value of name, enter: 
confstr(_CS PATH, NULL, (size t) 0) 


The confstr function returns the size of the buffer necessary. 
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confstr 


Return Values 


0 Indicates an error. When the specified name 
value: 


e Is invalid, errno is set to EINVAL. 


e Does not have a system-defined value, errno 
is not set. 


n The size of the buffer needed to hold the value. 


e When the value of the name argument is 
system-defined, confstr returns the size of 
the buffer needed to hold the entire value. 
If this return value is greater than the len 
value, the string returned as the buf value is 
truncated. 


e When the value of the Jen argument is set to 
0 or the buf value is NULL, confstr returns 
the size of the buffer needed to hold the 
entire system-defined value. The string value 
is not copied. 
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CON] Alpha, 164) 


conj (Alpha, 164) 


Returns the complex conjugate of its argument. 


Format 

#include <complex.h> 

double complex conj (double complex 2); 

float complex conjf (float complex 2); 

long double complex conjl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The conj functions return the complex conjugate of z, by reversing the sign of its 
imaginary part. 


Return Values 


x The complex conjugate value. 
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COPYSIGN Alpha, 164) 


Returns x with the same sign as y. 


Format 

#include <math.h> 

double copysign (double x, double y); 

float copysignf (float x, float y); (Alpha, 164) 

long double copysigni (long double x, long double y); (Alpha, 164) 
Arguments 

x 

A real value. 

A real value. 
Description 


The copysign functions return x with the same sign as y. IEEE 754 requires 
copysign(x,NaN), copysignf(«,NaN), and copysignl(x,NaN) to return +x or —x. 


Return Value 


x The value of x with the same sign as y. 
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Cos 


Format 


Argument 


Description 


Returns the cosine of its radian argument. 


#include <math.h> 

double cos (double x): 

float cosf (float x); (Alpha, 164) 

long double cosl (long double x); (Alpha, 164) 
double cosd (double x); (Alpha, 164) 

float cosdf (float x); (Alpha, 164) 


long double cosdl (long double x); (Alpha, 164) 


x 
A radian expressed as a real value. 


The cos functions return the cosine of their argument, measured in radians. 
The cosd functions return the cosine of their argument, measured in degrees. 


|x | = Infinity is an invalid argument. 


Return Values 


x The cosine of the argument. 


HUGE_VAL Indicates that the argument is too large; errno is 
set to ERANGE. 


REF-81 


cosh 


cosh 

Returns the hyperbolic cosine of its radian argument. 
Format 

#include <math.h> 

double cosh (double x); 

float coshf (float x); (Alpha, 164) 

long double coshl (long double x); (Alpha, 164) 
Argument 

x 

A radian expressed as a real number. 
Description 


The cosh functions return the hyperbolic cosine of x and are defined as (e**x + 
e**(—x))/2. 


Return Values 


x The hyperbolic cosine of the argument. 


HUGE_VAL Indicates that the argument is too large; errno is 
set to ERANGE. 
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cot 


Format 


Argument 


Description 


Returns the cotangent of its radian argument. 


#include <math.h> 

double cot (double x); 

float cotf (float x); (Aipha, 164) 

long double cotl (long double x); (Alpha, 164) 
double cotd (double x); (Alpha, 164) 

float cotdf (float x); (Alpha, 164) 


long double cotdl (long double x); (Alpha, 164) 


x 
A radian expressed as a real number. 


The cot functions return the cotangent of their argument, measured in radians. 
The cotd functions return the cotangent of their argument, measured in degrees. 


x = 0 is an invalid argument. 


Return Values 


x The cotangent of the argument. 
HUGE_VAL Indicates that the argument is zero; errno is set 
to ERANGE. 
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CPOW alpha, 164) 


Returns the complex power function x**y. 


Format 
#include <complex.h> 
double complex cpow (double complex x, double complex y); 
float complex cpowf (float complex x, float complex y): 


long double complex cpowl (long double complex x, long double complex y); 


Argument 


x 
A complex value. 


y 
A complex value. 


Description 


The cpow functions return the complex power function x**y, with a branch cut for 
the first parameter along the negative real axis. 


Return Values 


x The complex power function value. 
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CPrOj dipia, 164) 


Returns a projection of its argument onto the Riemann sphere. 


Format 

#include <complex.h> 

double complex cproj (double complex 2); 

float complex cprojf (float complex 2); 

long double complex cprojl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The cproj functions compute and return a projection of z onto the Riemann 
sphere: z projects to z, except that all complex infinities (even those with one 
infinite part and one NaN part) project to positive infinity on the real axis. If z 
has an infinite part, then cproj(z) is equivalent to: 


INFINITY + I * copysign(0.0, cimag(z)) 
Return Values 


x The value of the projection onto the Riemann 
sphere. 
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creal (pra, 164 


Returns the real part of its complex argument. 


Format 

#include <complex.h> 

double creal (double complex 2); 

float crealf (float complex z); 

long double creall (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The creal functions return the real part of z. 


Return Values 


x The real part value. 
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creat 


Format 


Arguments 


Creates a new file. 


#include <fcntl.h> 
int creat (const char *file_spec, mode_t mode); (Iso POSIX-1) 


int creat (const char *file_spec, mode_t mode, ... ); (HP C Extension) 


file_spec 
A null-terminated string containing any valid file specification. 


mode 

An unsigned value that specifies the file-protection mode. The compiler performs 
a bitwise AND operation on the mode and the complement of the current 
protection mode. 


You can construct modes by using the bitwise OR operator ( | ) to create mode 
combinations. The modes are: 


0400 OWNER: READ 
0200 OWNER: WRITE 
0100 OWNER: EXECUTE 
0040 GROUP:READ 

0020 GROUP: WRITE 
0010 GROUP: EXECUTE 
0004 WORLD:READ 
0002 WORLD: WRITE 
0001 WORLD: EXECUTE 


The system is given the same privileges as the owner. A WRITE privilege implies 
a DELETE privilege. 


Note 


To create files with OpenVMS RMS default protections using the UNIX 
system-call functions umask, mkdir, creat, and open, call mkdir, creat, 
and open with a file-protection mode argument of 0777 in a program that 
never specifically calls umask. These default protections include correctly 
establishing protections based on ACLs, previous versions of files, and so 
on. 


In programs that do vfork/exec calls, the new process image inherits 
whether umask has ever been called or not from the calling process image. 
The umask setting and whether the umask function has ever been called 
are both inherited attributes. 
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An optional argument list of character strings of the following form: 
"keyword = value", .. . "keyword = value" 

Or in the case of "acc" or "err", this form: 

"keyword" 


Here, keyword is an RMS field in the file access block (FAB) or record access 
block (RAB); value is valid for assignment to that field. Some fields permit you to 
specify more than one value. In these cases, the values are separated by commas. 


The RMS callback keywords "acc" and "err" are the only keywords that do not 
take values. Instead, they are followed by a pointer to the callback routine to 
be used, followed by a pointer to a user-specified value to be used as the first 
argument of the callback routine. For example, to set up an access callback 
routine called acc_callback whose first argument is a pointer to the integer 
variable first arg in a call to open, you can use the following statement: 


open("file.dat", O _RDONLY, 0 ,"acc", acc_callback, &first_arg) 


The second and third arguments to the callback routine must be pointers to a 
FAB and RAB, respectively, and the routine must have a return type of int. If 
the callback returns a value less than 0, the open, creat, or fopen fails. The 
error callback can correct the error condition and return a status greater than or 
equal to 0 to continue the creat call. Assuming the previous open statement, the 
function prototype for acc_callback would be similar to the following statement: 


#include <rms.h> 
int acc_callback(int *first_arg, struct FAB *fab, struct RAB *rab) ; 
FAB and RAB are defined in the <rms.h> header file, and the actual pointers 


passed to the routine are pointers to the RAB and FAB being used to open the file 
file.dat. 


If an access callback routine is established, then it will be called in the open-type 
routine immediately before the call to the RMS function sys$create or sys$open. 
If an error callback routine is established and an error status is returned from 
the sys$create or sys$open function, then the callback routine will be invoked 
immediately after the status is checked and the error value is discovered. 


Note 


Any manipulation of the RAB or FAB in a callback function could lead to 
serious problems in later calls to the HP C RTL I/O functions. 


Table REF—3 describes the RMS keywords and values. 


Table REF-3 RMS Valid Keywords and Values 


Keyword Value Description 
“acc” callback Access callback routine. 
“alg = n” decimal Allocation quantity. 
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Table REF-3 (Cont.) RMS Valid Keywords and Values 


Keyword Value Description 

“bls = n” decimal _ Block size. 

“etx = bin” string No translation of ’\n’ to the terminal. Use 
this for writing binary data to files. 

“ctx = cvt” string Negates a previous setting of “ctx=nocvt”. 
This is the default. 

“ctx = nocvt” string No conversion of Fortran carriage-control 
bytes. 

“ctx = rec” string Forces record mode access. 

“ctx = stm” string Forces stream mode access. 

“ctx = xplect” string Causes records to be written only when 
explicitly specified by a call to fflush, close, 
or fclose. 

“deq = n” decimal Default extension quantity. 

“dna = filespec” string Default file-name string. 

“err” callback Error callback routine. 

“fop = val, val, ...” File-processing options: 

ctg Contiguous. 

cbt Contiguous-best-try. 

dfw Deferred write; only applicable to files 
opened for shared access. 

dlt Delete file on close. 

tef Truncate at end-of-file. 

cif Create if nonexistent. 

sup Supersede. 

scf Submit as command file on close. 

spl Spool to system printer on close. 

tmd Temporary delete. 

tmp Temporary (no file directory). 

nef Not end-of-file. 

rck Read check compare operation. 

wek Write check compare operation. 

mxv Maximize version number. 

rwo Rewind file on open. 

pos Current position. 

rwe Rewind file on close. 

sqo File can only be processed in a sequential 
manner. 

“fsz = n” decimal _‘ Fixed header size. 

“sbe = n” decimal The requested number of global buffers for a 
file. 

“mbc = n” decimal Multiblock count. 

“mbf = n” decimal Multibuffer count. 

“mrs = n” decimal Maximum record size. 


(continued on next page) 
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Table REF-3 (Cont.) RMS Valid Keywords and Values 


Keyword Value Description 
“pmt=usr-prmpt” string Prompts for terminal input. Any RMS input 
from a terminal device will be preceded by 
“usr-prmpt” when this option and “rop=pmt” 
are specified. 
“rat = val, val...” Record attributes: 
cr Carriage-return control. 
blk Disallow records to span block boundaries. 
ftn Fortran print control. 
none Explicitly forces no carriage control. 
prn Print file format. 
“rfm = val” Record format: 
fix Fixed-length record format. 
stm RMS stream record format. 
stmlf Stream format with line-feed terminator. 
stmcr Stream format with carriage-return 
terminator. 
var Variable-length record format. 
vic Variable-length record with fixed control. 
udf Undefined. 
“rop = val, val...” Record-processing operations: 
asy Asynchronous I/O. 
cco Cancels Ctrl/O (used with Terminal I/O). 
cevt Capitalizes characters on a read from the 
terminal. 
eof Positions the record stream to the end-of-file 
for the connect operation only. 
nlk Do not lock record. 
pmt Enables use of the prompt specified by 
“pmt=usr-prmpt” on input from the terminal. 
pta Eliminates any information in the type- 
ahead buffer on a read from the terminal. 
rea Locks record for a read operation for this 
process, while allowing other accessors to 
read the record. 
rlk Locks record for write. 
rne Suppresses echoing of input data on the 
screen as it is entered on the keyboard. 
rnf Indicates that Ctrl/U, Ctrl/R, and DELETE 
are not to be considered control commands 
on terminal input, but are to be passed to the 
application program. 
rrl Reads regardless of lock. 
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Table REF-3 (Cont.) RMS Valid Keywords and Values 


Keyword Value Description 
syncsts Returns a success status of RMS$ SYNCH 
if the requested service completes its task 
immediately. 
tmo Timeout I/O. 
tpt Allows put/write services using sequential 
record access mode to occur at any point in 
the file, truncating the file at that point. 
ulk Prohibits RMS from automatically unlocking 
records. 
wat Wait until record is available, if currently 
locked by another stream. 
rah Read ahead. 
wbh Write behind. 
“rtv=n” decimal The number of retrieval pointers that RMS 
has to maintain in memory (0 to 127,255). 
“shr = val, val, ...” File sharing options: 
del Allows users to delete. 
get Allows users to read. 
mse Allows multistream connects. 
nil Prohibits file sharing. 
put Allows users to write. 
upd Allows users to update. 
upi Allows one or more writers. 
nql No query locking (file level). 
“tmo = n” decimal _IJ/O timeout value. 


In addition to these options, any option that takes a key value (such as “fop” 
or “rat”) can be negated by prefixing the value with “no”. For example, specify 
“fop=notmp” to clear the “tmp” bit in the “fop” field. 


Notes 


e While these options provide much flexibility and functionality, many 
of them can also cause severe problems if not used correctly. 


e You cannot share the default HP C for OpenVMS stream file I/O. 
If you wish to share files, you must specify “ctx=rec” to force record 
access mode. You must also specify the appropriate “shr” options 
depending on the type of access you want. 


e If you intend to share a file opened for append, you must specify 
appropriate share and record-locking options, to allow other accessors 
to read the record. The reason for doing this: the file is positioned at 
the end-of-file by reading records in a loop until end-of-file is reached. 


For more information on these options, see the OpenVMS Record Management 


Services Reference Manual manual. 
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Description 


The HP C RTL opens the new file for reading and writing, and returns the 
corresponding file descriptor. 


If the file exists: 


A version number one greater than any existing version is assigned to the 
newly created file. 


By default, the new file inherits certain attributes from the existing version of 
the file unless those attributes are specified in the creat call. The following 
attributes are inherited: 


— Record format (FAB$B_RFM) 

— Maximum record size (FAB$W_MRS) 
— Carriage control (FAB$B_RAT) 

— File protection 


When a new version of a file is created, and the named file already exists as a 
symbolic link, the file to which the symbolic link refers is created. 


If the file did not previously exist: 


It is given the file protection that results from performing a bitwise AND on 
the mode argument and the complement of the current protection mask. 


It defaults to stream format with line-feed record separator and implied 
carriage-return attributes. 


See also open, close, read, write, and lseek in this section. 


Return Values 
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n 
—1 


A file descriptor. 


Indicates errors, including protection violations, 
undefined directories, and conflicting file 
attributes. 


[no]crmode 


[no]crmode 


Format 


Example 


In the UNIX system environment, the crmode and nocrmode functions set and 
unset the terminal from cbreak mode. In cbreak mode, a single input character 
can be processed without pressing Return. This mode of single-character input is 
only supported with the Curses input routine getch. 


#include <curses.h> 
crmode( ) 


nocrmode( ) 


/* Program to demonstrate the use of crmod() and curses */ 
#include <curses.h> 


main () 


WINDOW *winl; 
char vert = '.', 
hor = '.', 


/* Initialize standard screen, turn echo off. */ 
initscr(); 
noecho () ; 


/* Define a user window. */ 
winl = newwin(22, 78, 1, 1); 


/* Turn on reverse video and draw a box on border. */ 
setattr( REVERSE) ; 

box(stdscr, vert, hor); 

mvwaddstr(winl, 2, 2, "Test cbreak input"); 

refresh(); 

wrefresh(winl) ; 


/* Set cbreak, do some input, and output it. */ 

crmode () ; 

getch() ; 

nocrmode(); /* Turn off cbreak. */ 

mvwaddstr(winl, 5, 5, str); 

mvwaddstr(winl, 7, 7, "Type something to clear the screen") ; 
wrefresh(winl) ; 


/* Get another character, then delete the window. */ 
getch() ; 

wclear(winl) ; 

touchwin(stdscr) ; 

endwin() ; 


} 


In this example, the first call to getch returns as soon as one character is entered, 
because crmode was called before getch was called. The second time getch is 
called, it waits until the Return key is pressed before processing the character 
entered, because nocrmode was called before getch was called the second time. 
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crypt 


Format 


The password encryption function. 


#include <unistd.h> 
#include <stdlib.h> 


char *crypt (const char *key, const char *salt) 


Function Variants 


Argument 


Description 


The crypt function has variants named crypt32 and crypté4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


key 
A user’s typed password. 


salt 
A 2-character string. 


The crypt function generates an encoded version of a password. It is based on 
the NBS Data Encryption Standard, with variations intended to frustrate use of 
hardware implementations of the DES for key search. 


The first argument to crypt is normally a user’s typed password. The second 

is a 2-character string chosen from the set [a-zA-Z0-9./]. The salt string is 

used to perturb the DES algorithm in one of 4096 different ways, after which the 
password is used as the key to encrypt repeatedly a constant string. The returned 
value points to the encrypted password, in the same alphabet as the salt. The 
first two characters are the salt itself. 


The return value from crypt points to a static data area whose content is 
overwritten by each call. 


See also encrypt and setkey. 


Return Value 
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pointer Pointer to the encrypted password. 


CSIN (lpha, 164 


CSIN (pha, 164) 


Returns the complex sine of its argument. 


Format 

#include <complex.h> 

double complex csin (double complex 2); 

float complex csinf (float complex 2); 

long double complex csin!| (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The csin functions compute the complex sine value of z. 
Return Values 


x The complex sine value. 
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csinh ipna, 164) 


csi n h (Alpha, I64) 


Returns the complex hyperbolic sine of its argument. 


Format 

#include <complex.h> 

double complex csinh (double complex 2); 

float complex csinhf (float complex 2); 

long double complex csinhl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The csinh functions compute the complex hyperbolic sine of z. 
Return Values 


x The complex hyperbolic sine value. 
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cst apna, 164) 


csq rt (Alpha, I64) 


Returns the complex square root of its argument. 


Format 

#include <complex.h> 

double complex csqrt (double complex 2); 

float complex csqrtf (float complex 2); 

long double complex csqrtl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The csqrt functions compute the complex square root of z, with a branch cut 
along the negative real axis. 


Return Values 
x The complex square root value in the range of 


the right half-plane (including the imaginary 
axis). 
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ctan apna, 164) 


Returns the complex tangent of its argument. 


Format 

#include <complex.h> 

double complex ctan (double complex 2); 

float complex ctanf (float complex 2); 

long double complex ctan! (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The ctan functions compute the complex tangent value of z. 
Return Values 


x The complex tangent value. 
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ctanh aipna, 164) 


Returns the complex hyperbolic tangent of its argument. 


Format 

#include <complex.h> 

double complex ctanh (double complex 2); 

float complex ctanhf (float complex 2); 

long double complex ctanhl (long double complex 2); 
Argument 

z 

A complex value. 
Description 


The ctanh functions compute the complex hyperbolic tangent value of z. 
Return Values 


x The complex hyperbolic tangent value. 
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ctermid 


Returns a character string giving the equivalence string of SYS$;COMMAND. 
This is the name of the controlling terminal. 

Format 
#include <stdio.h> 


char *ctermid (char “str; 


Function Variants 


The ctermid function has variants named ctermid32 and ctermidé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


Argument 


str 

Must be a pointer to an array of characters. If this argument is NULL, the 
file name is stored internally and might be overwritten by the next ctermid 
call. Otherwise, the file name is stored beginning at the location indicated by 
the argument. The argument must point to a storage area of length L_ctermid 
(defined by the <stdio.h> header file). 


Return Value 


pointer Points to a character string. 
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ctime, ctime_r 


Format 


Converts a time in seconds, since 00:00:00 January 1, 1970, to an ASCII string in 
the form generated by the asctime function. 


#include <time.h> 
char *ctime (const time_t *bintim); 


char *ctime_r (const time_t *bintim, char *buffer); so POSIX-1) 


Function Variants 


Arguments 


Description 


Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to this function that is 
equivalent to the behavior before OpenVMS Version 7.0. 


bintim 
A pointer to a variable that specifies the time value (in seconds) to be converted. 


buffer 
A pointer to a character array that is at least 26 bytes long. This array is used to 
store the generated date-and-time string. 


The ctime and ctime_r functions convert the time pointed to by bintim into a 
26-character string, and return a pointer to the string. 


The difference between the ctime_r and ctime functions is that the former puts 
its result into a user-specified buffer. The latter puts its result into thread- 
specific static memory allocated by the HP C RTL, which can be overwritten by 
subsequent calls to ctime or asctime; you must make a copy if you want to save 
it. 


On success, ctime returns a pointer to the string; ctime_r returns its second 
argument. On failure, these functions return the NULL pointer. 


The type time_t is defined in the <time.h> header file as follows: 
typedef long int time _t 


The ctime function behaves as if it called tzset. 


Note 


Generally speaking, UTC-based time functions can affect in-memory time- 
zone information, which is processwide data. However, if the system time 
zone remains the same during the execution of the application (which is 
the common case) and the cache of timezone files is enabled (which is the 
default), then the _r variant of the time functions asctime_r, ctime_r, 
gmtime_r, and localtime_r, is both thread-safe and AST-reentrant. 


If, however, the system time zone can change during the execution of 
the application or the cache of timezone files is not enabled, then both 
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variants of the UTC-based time functions belong to the third class of 
functions, which are neither thread-safe nor AST-reentrant. 


Return Values 


x A pointer to the 26-character ASCII string, if 
successful. 
NULL Indicates failure. 
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cuserid 


Format 


Returns a pointer to a character string containing the name of the user initiating 
the current process. 


#include <unistd.h> (x/Open, POSIX-1) 
#include <stdio.h> (X/Open) 


char *cuserid (char *str); 


Function Variants 


Argument 


The cuserid function has variants named cuserid32 and _cuseridé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


str 

If this argument is NULL, the user name is stored internally. If the argument 
is not NULL, it points to a storage area of length L_cuserid (defined by the 
<stdio.h> header file), and the name is written into that storage. If the user 
name is a null string, the function returns NULL. 


Return Values 


pointer Points to a string. 
NULL If the user name is a null string. 
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DECCS$CRTL_INIT 


Format 


Description 
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Allows you to call the HP C RTL from other languages or to use the HP C RTL 
when your main function is not in C. It initializes the run-time environment and 
establishes both an exit and condition handler. VAXCSCRTL_INIT is a synonym for 
DECCSCRTL_INIT. Hither name invokes the same routine. 


#include <signal.h> 
void DECC$CRTL_INIT(void); 


The following example shows a Pascal program that calls the HP C RTL using 
the DECC$CRTL_INIT function: 


$ PASCAL EXAMPLE1 
$ LINK EXAMPLE1 
$ TY EXAMPLE1.PAS 
PROGRAM TESTC(input, output) ; 
PROCEDURE DECCSCRTL_ INIT; extern; 
BEGIN 
DECCSCRTL_INIT; 
END 


A shareable image need only call this function if it contains an HP C function 
for signal handling, environment variables, I/O, exit handling, a default file 
protection mask, or if it is a child process that should inherit context. 


Although many of the initialization activities are performed only once, 
DECCSCRTL_INIT can safely be called multiple times. On OpenVMS VAX systems, 
DECCSCRTL_INIT establishes the HP C RTL internal OpenVMS exception handler 
in the frame of the routine that calls DECCS$CRTL_INIT each time DECCSCRTL_INIT 
is called. 


At least one frame in the current call stack must have that handler established 
for OpenVMS exceptions to get mapped to UNIX signals. 


decc$feature_get 


decc$feature_get 


Format 


Argument 


Description 


Calls decc$feature get value with a character-string feature name, rather than 
an index. 


#include <unixlib.h> 


int decc$feature_get (const char *name, int mode); 


name 
Pointer to a character string passed as a name in the list of supported features. 


mode 

An integer indicating which feature value to return. The values for mode are: 
__FEATURE_MODE_DEFVAL Default value 
__FEATURE_MODE_CURVAL Current value 
__FEATURE_MODE_MINVAL Minimum value 
__FEATURE_MODE_MAXVAL Maximum value 


__FEATURE_MODE_INIT_STATE Initialization state 


The decc$feature_get function allows you to call the decc$feature get value 
function with a character-string feature name, rather than an index into an 
internal C RTL table. 


On error, —1 is returned and errno is set to indicate the error. 


See also decc$feature_get_value, decc$feature_get_index, 
decc$feature get name, deccSfeature set, decc$feature set value, 
decc$feature_show, and decc$feature_show_all. 


Return Values 


n An integer corresponding to the specified name 
and mode arguments. 


—1 Indicates an error; errno is set. 
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decc$feature_get_index 


Returns an index for accessing feature values. 


Format 
#include <unixlib.h> 


int decc$feature_get_index (char *name); 


Argument 


name 
Pointer to a character string passed as a name in the list of supported features. 


Description 


The decc$feature_ get index function looks up the string passed as name in 
the list of supported features. If the name is found, decc$feature_get_index 
returns a (nonnegative) index that can be used to set or retrieve the values for 
the feature. The comparison for name is case insensitive. 


On error, —1 is returned and errno is set to indicate the error. 


See also decc$feature_ get, decc$feature get value, decc$feature get name, 
decc$feature set, decc$feature set value, decc$feature show, and 
decc$feature_show_ all. 


Return Values 
n A nonnegative index that can be used to set or 


retrieve the specified values for the feature. 
—1 Indicates an error; errno is set. 
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decc$feature_get_name 


decc$feature_get_name 


Format 


Argument 


Description 


Returns a feature name. 


#include §<unixlib.h> 


char *decc$feature_get_name (int index); 


index 
An integer value from 0 to the highest allocated feature. 


The decc$feature_ get name function returns a pointer to a null-terminated 
string containing the name of the feature for the entry specified by index. The 
index value can be 0 to the highest allocated feature. If there is no feature 
corresponding to the index value, then the function returns a NULL pointer. 


On error, NULL is returned and errno is set to indicate the error. 


See also decc$feature get, decc$feature get index, decc$feature get value, 
decc$feature set, decc$feature set value, decc$feature show, and 
deccS$feature_ show all. 


Return Values 


x Pointer to a null-terminated string containing 
the name of the feature for the entry specified by 
index. 

NULL Indicates an error; errno is set. 
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decc$feature_get_value 


decc$feature_get_value 


Format 


Arguments 


Description 


Returns a feature value specified by the index and mode arguments. 


#include <unixlib.h> 


int decc$feature_get_value (int index, int mode): 


index 
An integer value from 0 to the highest allocated feature. 


mode 

An integer indicating which feature value to return. The values for mode are: 
__FEATURE_MODE_DEFVAL Default value 
__FEATURE_MODE_CURVAL Current value 
__FEATURE_MODE_MINVAL Minimum value 
__FEATURE_MODE_MAXVAL Maximum value 


__FEATURE_MODE_INIT_STATE Initialization state 


The decc$feature_get_value function retrieves a value for the feature specified 
by index. The mode determines which value is returned. 


The default value is what is used if not set by a logical name or overidden by a 
call to decc$feature_ set value. 


If mode = 4, then the initialization state is returned. Values for the initialization 
state are: 


0 not initialized 

1 set by logical name 

2 forced by decc$feature set value 
—1— initialized to default value 


On error, —1 is returned and errno is set to indicate the error. 


See also decc$feature_ get, decc$feature get index, decc$feature get_name, 
decc$feature set, decc$feature set value, decc$feature show, and 
decc$feature_show_ all. 


Return Values 
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n An integer corresponding to the specified index 
and mode arguments. 


—1 Indicates an error; errno is set. 


decc$feature_set 


decc$feature_set 


Format 


Argument 


Description 


Calls decc$feature set value with a character-string feature name, rather than 
an index. 


#include <unixlib.h> 


int decc$feature_set (const char *name, int mode, int value); 


name 
Pointer to a character string passed as a name in the list of supported features. 


mode 

An integer indicating which feature value to return. The values for mode are: 
__FEATURE_MODE_DEFVAL Default value 
__FEATURE_MODE_CURVAL Current value 
__FEATURE_MODE_MINVAL Minimum value 
__FEATURE_MODE_MAXVAL Maximum value 


__FEATURE_MODE_INIT_STATE Initialization state 


value 
The feature value to be set. 


The decc$feature_set function allows you to call the decc$feature set value 
function with a character-string feature name, rather than an index into an 
internal C RTL table. 


If successful, the function returns the previous value. 
On error, —1 is returned and errno is set to indicate the error. 


See also decc$feature set value, decc$feature get, decc$feature get index, 
decc$feature get name, decc$feature get value. decc$feature show, and 
decc$feature_show all. 


Return Values 


n The previous feature value. 
—1 Indicates an error; errno is set. 
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decc$feature_set_value 


decc$feature_set_value 


Format 


Arguments 


Description 


Sets the default value or the current value for the feature specified by index. 


#include <unixlib.h> 


int decc$feature_set_value (int index, int mode, int value): 


index 
An integer value from 0 to the highest allocated feature. 


mode 
An integer indicating whether to set the default or current feature value. The 
values for mode are: 


0 default value 
1 current value 


value 
The feature value to be set. 


The decc$feature set value function sets the default value or the current value 
(as determined by the mode argument) for the feature specified by index. 


If this function is successful, it returns the previous value. 
On error, —1 is returned and errno is set to indicate the error. 


See also decc$feature get, decc$feature get index, decc$feature get name, 
decc$feature get value, decc$feature set, decc$feature show, and 
decc$feature_show_ all. 


Return Values 
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n The previous feature value. 


—1 Indicates an error; errno is set. 


decc$feature_show 


decc$feature_show 


Format 


Argument 


Description 


Displays all feature values for the specified feature name. 


#include <unixlib.h> 


int decc$feature_show (const char *name); 


name 
Pointer to a character string passed as a name in the list of supported features. 


The decc$feature_show function displays to stdout all values for the specified 
feature name. For example: 


Saas aa C RTL Feature Name --------- Cur Def Min Max Ini 
DECC$V62_ RECORD GENERATION 0 0 0 1 =1 
On error, —1 is returned and errno is set to indicate the error. 


See also decc$feature get, decc$feature get index, decc$feature get name, 
decc$feature_get_value, decc$feature set, decc$feature_set_value, and 
deccS$feature_ show all. 


Return Values 


0 Indicates success. 
—1 Indicates an error; errno is set. 
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decc$feature_show_all 


decc$feature_show_all 


Displays all feature values for all feature names. 


Format 
#include <unixlib.h> 


int decc$feature_show_all (void): 


Description 


The decc$feature show all function displays to stdout all values for all feature 
names. 


On error, —1 is returned and errno is set to indicate the error. 


See also decc$feature_ get, decc$feature_get_index, decc$feature_get_name, 
decc$feature get value, decc$feature set, decc$feature set value, and 
deccSfeature_show. 


Return Values 


0 Indicates success. 
—1 Indicates an error; errno is set. 
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decc$fix_time 


decc$fix_time 


Converts OpenVMS binary system times to UNIX binary times. 


Format 
#include <unixlib.h> 
unsigned int decc$fix_time (void *vms_time); 
Argument 
vms_time 
The address of a quadword containing an OpenVMS binary time: 
unsigned int quadword[2] ; 
unsigned int *vms_ time = quadword; 
Description 


The decc$fix time routine converts an OpenVMS binary system time (a 64-bit 
quadword containing the number of 100-nanosecond ticks since 00:00 November 
17, 1858) to a UNIX binary time (a longword containing the number of seconds 
since 00:00 January 1, 1970). This routine is useful for converting binary times 
returned by OpenVMS system services and RMS services to the format used by 
some HP C RTL routines, such as ctime and localtime. 


Return Values 


x A longword containing the number of seconds 
since 00:00 January 1, 1970. 
(unsigned int)(—1) Indicates an error. Be aware, that a return value 


of (unsigned int)(—1) can also represent a valid 
date of Sun Feb 7 06:28:15 2106. 


Example 


#include <unixlib.h> 
#include <stdio.h> 
#include <starlet.h> /* OpenVMS specific SYS$ routines) */ 


main () 


unsigned in 
unsigned in 


t current _vms time[2]; /*quadword for OpenVMS time*/ 
t number of seconds; /* number of seconds */ 
/* first get the current system time */ 
sys$gettim(&current_vms_time[0]) ; 


/* fix the time */ 
number of seconds = decc$fix time(&current_vms time[0]) ; 


printf ("Number of seconds since 00:00 January 1, 1970 = %d", 
number of seconds) ; 


This example shows how to use the decc$fix time routine in HPC. It also 
shows the use of the SYS$GETTIM system service. 
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decc$from_vms 


decc$from_vms 


Format 


Arguments 


Description 


Converts OpenVMS file specifications to UNIX style file specifications. 


#include <unixlib.h> 


int decc$from_vms (const char *vms_filespec, int action_routine, int wild_flag); 


vms_filespec 
The address of a null-terminated string containing a name in OpenVMS file 
specification format. 


action_routine 

The address of a routine that takes as its only argument a null-terminated string 
containing the translation of the given OpenVMS file name to a valid UNIX style 
file name. 


If the action_routine returns a nonzero value (TRUE), file translation continues. 
If it returns a zero value (FALSE), no further file translation takes place. 


wild_flag 

Either 0 or 1, passed by value. If a 0 is specified, wildcards found in ums_filespec 
are not expanded. Otherwise, wildcards are expanded and each one is passed to 
action_routine. Only expanded file names that correspond to existing UNIX style 
files are included. 


The decc$from_vms routine converts the given OpenVMS file specification into 
the equivalent UNIX style file specification. It allows you to specify OpenVMS 
wildcards, which are translated into a list of corresponding existing files in UNIX 
style file specification format. 


Return Value 


Example 
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x The number of file names that result from the 
specified OpenVMS file specification. 


/* This example must be run as a foreign command */ 
/* and be supplied with an OpenVMS file specification. */ 


#include <unixlib.h> 
#include <stdio.h> 


int main(int argc, char *argv[]) 
int number found; /* number of files found */ 
int print_name() ; /* name printer */ 


printf ("Translating: %s\n", argv[1]); 
number found = decc$from_vms(argv[1], print_name, 1); 
printf ("\n%d files found", number found) ; 


decc$from_vms 


/* print the name on each line */ 
print_name(char *name) 


printf ("\n%s", name) ; 
/* will continue as long as success status is returned */ 
return (1); 


} 


This example shows how to use the decc$from_vms routine in HP C. It produces 

a simple form of the 1s command that lists existing files that match an OpenVMS 
file specification supplied on the command line. The matching files are displayed 

in UNIX style file specification format. 
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decc$match_wild 


decc$match_wild 


Matches a string to a pattern. 


Format 
#include <unixlib.h> 


int decc$match_wild (char *test_string, char *string_pattern); 


Arguments 


test_string 
The address of a null-terminated string. 


string_pattern 

The address of a string containing the pattern to be matched. This pattern can 
contain wildcards (such as asterisks (*), question marks (?), and percent signs 
(% ) as well as regular expressions (such as the range [a-z]). 


Description 


The decc$match wild routine determines whether the specified test string is a 
member of the set of strings specified by the pattern. 


Return Values 


1 (TRUE) The string matches the pattern. 
0 (FALSE) The string does not match the pattern. 


Example 


/* Define as a foreign command and then provide */ 
/* two arguments: test_string, string pattern. */ 


#include <unixlib.h> 

#include <stdio.h> 

int main(int argc, char *argv[]) 
{ 
if (decc$match wild(argv[1], argv[2])) 
printf("\n%s matches %s", argv[1], argv[2]); 


else 
printf ("\n%s does not match %s", argv[1], argv[2]); 
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decc$record_read 


decc$record_read 


Format 


Arguments 


Description 


Reads a record from a file. 


#include <stdio.h> 


int decc$record_read (FILE *fp, void “buffer, int nbytes); 


fp 
A file pointer. The specified file pointer must refer to a file currently opened for 
reading. 


buffer 
The address of contiguous storage in which the input data is placed. 


nbytes 
The maximum number of bytes involved in the read operation. 


The decc$record_read function is specific to OpenVMS systems and should not 
be used when writing portable applications. 


This function is equivalent to the read function, except that the first argument is 
a file pointer, not a file descriptor. 


Return Values 


x The number of characters read. 


-1 Indicates a read error, including physical input 
errors, illegal buffer addresses, protection 
violations, undefined file descriptors, and so 
forth. 
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decc$record_write 


decc$record_write 


Format 


Arguments 


Description 


Writes a record to a file. 


#include <stdio.h> 


int decc$record_write (FILE “fp, void “buffer, int nbytes); 


fp 
A file pointer. The specified file pointer must refer to a file currently opened for 
writing or updating. 


buffer 
The address of contiguous storage from which the output data is taken. 


nbytes 
The maximum number of bytes involved in the write operation. 


The decc$record_write function is specific to OpenVMS systems and should not 
be used when writing portable applications. 


This function is equivalent to the write function, except that the first argument 
is a file pointer, not a file descriptor. 


Return Values 
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x The number of bytes written. 

—1 Indicates errors, including undefined file 
descriptors, illegal buffer addresses, and physical 
I/O errors. 


decc$set_child_default_dir (ira, 164 


decc$set_child_default_ dir cipia, 164) 


Format 


Arguments 


Description 


Sets the default directory for a child process spawned by a function from the exec 
family of functions. 


#include <unixlib.h> 


int decc$set_child_default_dir (const char *default_dir); 


default_dir 
The default directory specification for child processes, or NULL. 


By default, child processes created by one of the exec family of functions inherit 
the default (working) directory of their parent process. 


The decc$set_ child default dir function lets you set the default directory for 
a child process. After calling decc$set_ child default dir, newly spawned child 
processes have their default directory set to default_dir as they begin execution. 
The default_dir argument must represent a valid directory specification, or 
results of the call are unpredictable (subsequent calls to the child process might 
fail without notification). Both OpenVMS and UNIX style file specifications are 
supported for this function call. 


You can reestablish the default behavior by specifying default_dir as NULL. 
Subsequently, newly created child processes will inherit their parent’s working 
directory. 


Return Values 


0 Successful completion. The new inherited default 
directory was established. 


—1 Indicates failure. No new default directory was 
established for child processes. The function sets 
errno to one of the following values: 


e ENOMEM - Insufficient memory 


e ENAMETOOLONG -— default_dir is too 
long to issue the required SET DEFAULT 
command. 
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decc$set_child_standard_streams 


decc$set_child_standard_streams 


Format 


Arguments 


Description 
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For a child spawned by a function from the exec family of functions, associates 
specified file descriptors with a child’s standard streams: stdin, stdout, and 
stderr. 


#include <unixlib.h> 
int decc$set_child_standard_streams (int fd7, int fd2, int fa3); 


fd1 

The file associated with this file descriptor in the parent process is associated 
with file descriptor number 0 (stdin) in the child process. If —1 is specified, the 
file associated with the parent’s file descriptor number 0 is used (the default). 


fd2 

The file associated with this file descriptor in the parent process is associated 
with file descriptor number 1 (stdout) in the child process. If —1 is specified, the 
file associated with the parent’s file descriptor number 1 is used (the default). 


fd3 

The file associated with this file descriptor in the parent process is associated 
with file descriptor number 2 (stderr) in the child process. If —1 is specified, the 
file associated with the parent’s file descriptor number 2 is used (the default). 


The decc$set_child_ standard streams function allows mapping of specified file 
descriptors to the child’s stdin/stdout/stderr streams, thereby compensating, to 
a certain degree, the lack of a real fork function on OpenVMS systems. 


On UNIX systems, the code between fork and exec is executed in the context of 
the child process: 


parent: 
create pipes pl, p2 and p3 
fork 

child: 


map stdin to pl like dup2(pl1, stdin); 
map stdout to p2 like dup2(p2, stdout); 
map stderr to p3 like dup2(p3, stderr); 
exec (child reads from stdin and writes to stdout and stderr) 
exit 
parent: 
communicates with the child using pipes 


On OpenVMS systems, the same task could be achieved as follows: 


decc$set_child_standard_streams 


parent: 
create pipes pl, p2 and p3 
decc$set_child_ standard _streams(pl, p2, p3); 
vfork 
exec (child reads from stdin and writes to stdout and stderr) 
parent: 
communicates with the child using pipes 


Once established through the call to decc$set_child_standard_streams, the 
mapping of the child’s standard streams remains in effect until explicitly disabled 
by one of the following calls: 


decc$set_child_standard_streams(-1, -1, -1); 
Or: 
decc$set_child_standard_streams(0, 1, 2); 


Usually, the child process inherits all its parent’s open file descriptors. 
However, if file descriptor number n was specified in the call to 
decc$set_ child standard streams, it is not inherited by the child process 
as file descriptor number n; instead, it becomes one of the child’s standard 
streams. 


Notes 


e Standard streams can be redirected only to pipes. 


e Ifthe parent process redefines the DCL DEFINE command, this 
redefinition is not in effect in a subprocess with user-defined channels. 
The subprocess always sees the standard DCL DEFINE command. 


e It is the responsibility of the parent process to consume all the 
output written by the child process to stdout and stderr. Depending 
on how the subprocess writes to stdout and stderr—in wait or 
nowait mode—the subprocess might be placed in LEF state waiting 
for the reader. For example, DCL writes to SYS$OUTPUT and 
SYS$ERROR in a wait mode, so a child process executing a DCL 
command procedure will wait until all the output is read by the 
parent process. 


Recommendation: Read the pipes associated with the child process’ 
stdout and stderr in a loop until an EOF message is received, or 
declare write attention ASTs on these mailboxes. 


e The amount of data written to SYS$OUTPUT depends on the 
verification status of the process (SET VERIFY/NOVERIFY 
command); the subprocess inherits the verification status of the 
parent process. It is the caller’s responsibility to set the verification 
status of the parent process to match the expected amount of data 
written to SYS$OUTPUT by the subprocess. 


e Some applications, like DTM, define SYS$ERROR as SYS$OUTPUT. 
If stderr is not redefined by the caller, it is set in the subprocess 
as the parent’s SYS$ERROR, which in this case translates to the 
parent’s SYS$OUTPUT. 


If the caller redefines stdout to a pipe and does not redefine stderr, 
output sent to stderr goes to the pipe associated with stdout, and the 
amount of data written to this mailbox may be more than expected. 
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decc$set_child_standard_streams 


Although redefinition of any subset of standard channels is supported, 
it is always safe to explicitly redefine all of them (or at least stdout 
and stderr) to avoid this situation. 


e For a child process executing a DCL command procedure, 
SYS$COMMAND is set to the pipe specified for the child’s stdin 
so that the parent process can feed the child requesting data from 
SYS$COMMAND through the pipe. For DCL command procedures, it 
is impossible to pass data from the parent to the child by means of the 
child’s SYS$INPUT because for a command procedure, DCL defines 
SYS$INPUT as the command file itself. 


Return Values 


x The number of file descriptors set for the child. 
This number does not include file descriptors 
specified as —1 in the call. 

-1 indicates that an invalid file descriptor was 
specified; errno is set to EBADF. 


Example 


parent.c 


#include <stdio.h> 
#include <string.h> 
#include <unistd.h> 


int decc$set_child_standard_streams(int, int, int); 
main() 

int fdin[2], 
char BeErat: 
int nbytes 


fdout [2], fderr[2]; 
"parent writing to child’s stdin"; 


! 


pipe (fdin) ; 
pipe (fdout) ; 
pipe (fderr) ; 


if ( viork() <= 0 } 4 
decc$set_child_standard_streams(fdin[0], fdout[1], fderr[1]); 
execl( "child", "child" ); 


else { 
write(fdin[1], msg, sizeof (msg) ) ; 
nbytes = read(fdout[0], buf, sizeof (buf) ); 


buf [nbytes] = '\0'; 

puts (buf) ; 

nbytes = read(fderr[0], buf, sizeof (buf) ); 
buf [nbytes] = '\0'; 

puts (buf) ; 


} 
} 


child.c 


#include <stdio.h> 
#include <unistd.h> 
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decc$set_child_standard_streams 


main () 


{ 


char msg[] = "child writing to stderr"; 
char buf [80]; 

int nbytes; 

nbytes = read(0, buf, sizeof (buf) ); 
write(1, buf, nbytes) ; 

write(2, msg, sizeof (msg) ) ; 


} 


child.com 


$ read sys$command s 
$ write sysSoutput s 
$ write sysSerror "child writing to stderr" 


This example program returns the following for both child.c and child.com: 


$ run parent 
parent writing to child's stdin 
child writing to stderr 


Note that in order to activate child.com, you must explicitly specify 
execl ("child.com", ...) in the parent.c program. 
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decc$set_reentrancy 


decc$set_reentrancy 


Format 


Argument 


Description 
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Controls the type of reentrancy that reentrant HP C RTL routines will exhibit. 


#include <reentrancy.h> 


int decc$set_reentrancy (int type); 


type 

The type of reentrancy desired. Use one of the following values: 

¢ C$C_MULTITHREAD — Designed to be used in conjunction with the 
DECthreads product. It performs DECthreads locking and never disables 
ASTs. DECthreads must be available on your system to use this form of 
reentrancy. 


e C$C_AST — Uses the _BBSSI vax only) or __TESTBITSSI (ipha, 164) built-in 
function to perform simple locking around critical sections of RTL code, and it 
may additionally disable asynchronous system traps (ASTs) in locked regions 
of code. This type of locking should be used when AST code contains calls to 
HP C RTL I/O routines, or when the user application disables ASTs. 


¢ C$C_TOLERANT — Uses the _BBSSI (vax only) or __TESTBITSSI (Alpha, 164) 
built-in function to perform simple locking around critical sections of RTL 
code, but ASTs are not disabled. This type of locking should be used when 
ASTs are used and must be delivered immediately. TOLERANT is the default 
reentrancy type. 


e C$C_NONE — Gives optimal performance in the HP C RTL, but does 
absolutely no locking around critical sections of RTL code. It should only 
be used in a single-threaded environment when there is no chance that the 
thread of execution will be interrupted by an AST that would call the HP C 
RTL. 


The reentrancy type can be raised but never lowered. The ordering of reentrancy 
types from low to high is C6C_NONE, C$C_TOLERANT, C$C_AST and C$C_ 
MULTITHREAD. For example, once an application is set to multithread, a call 
to set the reentrancy to AST is ignored. A call to decc$set_reentrancy that 
attempts to lower the reentrancy type returns a value of —1. 


Use the decc$set_reentrancy function to change the type of reentrancy exhibited 
by reentrant routines. 


decc$set_reentrancy must be called exclusively at the non-AST level. 


In an application using DECthreads, DECthreads automatically sets the 
reentrancy to multithread. 


decc$set_reentrancy 


Return Value 


type The type of reentrancy used before this call. 
a1 The reentrancy was set to a lower type. 
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decc$to_vms 


decc$to_vms 


Format 


Arguments 
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Converts UNIX style file specifications to OpenVMS file specifications. 


#include <unixlib.h> 


int decc$to_vms (const char *unix_style_filespec, int (*action_routine)(char *OpenVMS_style_filespec, 
int type_of_file), int allow_wild, int no_directory); 


unix_style_filespec 
The address of a null-terminated string containing a name in UNIX style file 
specification format. 


action_routine 
The address of a routine called by decc$to_vms that accepts the following 
arguments: 


e A pointer to a null-terminated string that is the result of the translation to 
OpenVMS format. 


e An integer that has one of the following values: 


Value Translation 


0 (DECC$K_FOREIGN) A file on a remote system that is not 
running the OpenVMS or VAXELN 
operating system. 

1 (DECC$K_FILE) The translation is a file. 

2 (DECC$K_DIRECTORY) The OpenVMS translation of the UNIX 
style file name is a directory. 


These values can be defined symbolically with the symbols DECC$K_ 
FOREIGN, DECC$K_FILE, and DECC$K_DIRECTORY. See the example for 
more information. 


If action_routine returns a nonzero value (TRUE), file translation continues. If it 
returns a 0 value (FALSE), no further file translation takes place. 


allow_wild 

Either 0 or 1, passed by value. If a 0 is specified, wildcards found in wnix_style_ 
filespec are not expanded. Otherwise, wildcards are expanded and each one is 
passed to action_routine. Only expanded file names that correspond to existing 
OpenVMS files are included. 


no_directory 
An integer that has one of the following values: 


Value Translation 


0 Directory allowed. 


decc$to_vms 


Value Translation 


Prevent expansion of the string as a directory name. 
Forced to be a directory name. 


Description 


The decc$to_vms function converts the given UNIX style file specification into 
the equivalent OpenVMS file specification (in all uppercase letters). It allows you 
to specify UNIX style wildcards, which are translated into a list of corresponding 
OpenVMS files. 


See Section 1.6 for descriptions of the following feature logicals that can affect the 
behavior of decc$to_vms: 


DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION 
DECC$NO_ROOTED_SEARCH_LISTS 


Return Value 


x The number of file names that result from the 
specified UNIX style file specification. 


Example 


/* Translate "UNIX" wildcard file names to OpenVMS names.*/ 
/* Define as a foreign command and provide the name as */ 
/* an argument. */ 


#include <unixlib.h> 

#include <stdio.h> 

int print _name(char *, int); 

int main(int argc, char *argv[]) 


int number found; /* number of files found */ 


printf ("Translating: %s\n", argv[1]); 


printf ("sd files found\n", number found) ; 


number found = decc$to vms(argv[1], print_name, 1, 0); 


} 


/* action routine that prints name and type on each line */ 


int print_name(char *name, int type) 


if (type == DECCS$K_DIRECTORY) 

printf ("directory: %s\n", name) ; 

lse if (type == DECCSK_FOREIGN) 

printf ("remote non-VMS: %s\n", name) ; 


oO 


else 
printf ("file: s\n", name) ; 


/* Translation continues as long as success status is returned */ 
return (1); 


This example shows how to use the decc$to_vms routine in HP C. It takes a 
UNIX style file specification argument and displays, in OpenVMS file specification 
format, the name of each existing file that matches it. 
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decc$translate_vms 


decc$translate_vms 


Translates OpenVMS file specifications to UNIX style file specifications. 


Format 
#include <unixlib.h> 
char *decc$translate_vms (const char *vms_filespec); 
Argument 
vms_filespec 
The address of a null-terminated string containing a name in OpenVMS file 
specification format. 
Description 


The decc$translate vms function translates the given OpenVMS file specification 
into the equivalent UNIX style file specification, whether or not the file exists. 
The translated name string is stored in a thread-specific memory, which is 
overwritten by each call to decc$translate vms from the same thread. 


This function differs from the decc$from_vms function, which does the conversion 
for existing files only. 


Return Values 


x The address of a null-terminated string 
containing a name in UNIX style file specification 
format. 


0 Indicates that the file name is null or 
syntactically incorrect. 


—1 Indicates that the file specification contains 
an ellipsis (for example, |... Ja.dat), but is 
otherwise correct. You cannot translate the 
OpenVMS ellipsis syntax into a valid UNIX style 
file specification. 


Example 


/* Demonstrate translation of a "UNIX" name to OpenVMS */ 
/* form, define a foreign command, and pass the name as */ 
/* the argument. */ 


#include <unixlib.h> 
#include <stdio.h> 


int main(int argc, char *argv[]) 


char *ptr; /* translation result */ 
ptr = deccS$translate vms( argv[1] ); 


if ((int) ptr == 0 || (int) ptr == -1) 
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printf( "could not translate %s\n", argv[1]); 
else 
printf( "%s is translated to %s\n", argv[1], ptr ); 
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decc$validate_wchar 


Format 


Argument 


Description 


Confirms that its argument is a valid wide character in the current program’s 
locale. 


#include <unistd.h> 


int decc$validate_wchar (wchar_t we); 


wc 
Wide character to be validated. 


The decc$validate wchar function provides a convenient way to verify whether 
a specified argument of wchar_t type is a valid wide character in the current 
program’s locale. 


One reason to call decc$validate wchar is that the isw* wide-character 
classification functions and macros do not validate their argument before 
dereferencing the classmask array describing character properties. Passing 

an isw* function a value that exceeds the maximum wide-character value for the 
current program’s locale can result in an attempt to access memory beyond the 
allocated classmask array. 


A standard way to validate a wide character is to call the wctomb function, but 
this way is less convenient because it requires declaring a multibyte character 
array of sufficient size and passing it to wctomb. 


Return Values 
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1 Indicates that the specified wide character is a 
valid wide character in the current program’s 
locale. 

0 Indicates that the specified wide character is not 


a valid wide character in the current program’s 
locale. errno is not set. 


decc$write_eof_to_mbx 


decc$write_eof_ to mbx 


Format 


Argument 


Description 


Writes an end-of-file message to the mailbox. 


#include <unistd.h> 


int decc$write_eof_to_mbx (int fd); 


fd 
File descriptor associated with the mailbox. 


The decc$write eof to _mbx function writes end-of-file message to the mailbox. 


For a mailbox that is not a pipe, the write function called with an nbytes 
argument value of 0 sends an end-of-file message to the mailbox. For a pipe, 
however, the only way to write an end-of-file message to the mailbox is to close 
the pipe. 


If the child’s standard input is redirected to a pipe through a call to the 
decc$set_child standard streams function, the parent process can call 
decc$write eof to mbx for this pipe to send an EOF message to the child. 

It has the same effect as if the child read the data from a terminal, and Ctrl/Z 
was pressed. 


After a call to decc$write_eof_to_mbx, the pipe can be reused for communication 
with another child, for example. This is the purpose of decc$write eof to _mbx: 
to allow reuse of the pipe instead of having to close it just to send an end-of-file 
message. 


Return Values 


Example 


0 Indicates success. 


—1 Indicates failure; errno and vaxcSerrno are 
set according to the failure status returned by 
SYS$QIOW. 


/* decc$write_ eof to mbx example.c */ 


include <errno.h> 
include <stdio.h> 
#include <string.h> 


include <fcntl.h> 
#include <unistd.h> 
include <unixio.h> 


#include <descrip.h> 
include <ssdef.h> 
include <starlet.h> 


int decc$write eof to _mbx( int ); 
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main () 
{ 
int status, nbytes, failed = 0; 
int fd, £d2[2]; 
short int channel; 
SDESCRIPTOR (mbxname_dsc , "TEST MBX" ); 
char ¢c; 


/* first try a mailbox created by SYSSCREMBX */ 


status = sys$crembx(0, &channel, 0, 0, 0, 0, &mbxname dsc, 0, 0); 
if ( status != SS$ NORMAL ) { 
printf ("sys$crembx failed: %s\n",strerror(EVMSERR, status) ); 


failed = 1; 
if ( (fd = open(mbxname_dsc.dsc$a_pointer, O_RDWR, 0)) == -1) { 
perror("? open mailbox") ; 
failed = 1; 
if ( decc$write eof to mbx(fd) == -1) { 
perror("? decc$write eof to _mbx to mailbox") ; 
failed = 1; 


} 


if ( (nbytes = read(fd, &c, 1)) != 0 || errno != 0) { 
perror("? read mailbox") ; 
printf ("? nbytes = %d\n", nbytes) ; 


failed = 1; 
} 
if ( close(fd) == -1) { 
perror("? close mailbox") ; 
failed = 1; 
} 
/* Now do the same thing with a pipe */ 
errno = 0; /* Clear errno for consistency */ 
if ( pipe(fd2) == -1) { 
perror("? opening pipe") ; 
failed = 1; 
} 
if ( decc$write eof to mbx(fd2[1]) == -1) { 
perror("? deccSwrite eof to _mbx to pipe"); 
failed = 1; 


if ( (nbytes = read(f£d2[0], &c, 1)) != 0 || errno !=0) { 
perror("? read pipe"); 
printf("? nbytes = %d\n", nbytes) ; 
failed = 1; 


/* Close both file descriptors involved with the pipe */ 


if ( close(fd2[0]) == -1) { 
perror ("close (fd2[0])"); 
failed = 1; 

} 

if ( close(fd2[1]) == -1) { 
perror ("close (fd2[1])"); 
failed = 1; 
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if ( failed ) 

puts("?Example program failed") ; 
else 

puts ("Example ran to completion") ; 


This example program produces the following result: 


Example ran to completion 
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[w]delch 
Delete the character on the specified window at the current position of the cursor. 
The delch function operates on the stdscr window. 
Format 
#include <curses.h> 
int delch( ); 
int wdelch (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Description 


All of the characters to the right of the cursor on the same line are shifted to the 
left, and a blank character is appended to the end of the line. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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delete 


delete 


Format 


Argument 


Description 


Deletes a file. 


#include <unixio.h> 


int delete (const char *file_spec); 


file_spec 
A pointer to the string that is an OpenVMS or UNIX style file specification. The 
file specification can include a wildcard in its version number (but not in any 


other part of the file spec). So, for example, files of the form filename.txt;* can be 
deleted. 


If you specify a directory in the file name and it is a search list that contains an 
error, HP C for OpenVMS Systems interprets it as a file error. 


When delete is used to delete a symbolic link, the link itself is deleted, not the 
file to which it refers. 


The remove and delete functions are functionally equivalent in the HP C RTL. 


See also remove. 


Note 


The delete routine is not available to C++ programmers because it 
conflicts with the C++ reserved word delete. C++ programmers should 
use the ANSI/ISO C standard function remove instead. 


Return Values 


0 Indicates success. 
nonzero value Indicates that the operation has failed. 
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[w]deletelin 


Delete the line at the current position of the cursor. The deleteln function acts 
on the stdscr window. 


Format 

#include <curses.h> 

int deleteln( ); 

int wdeleteln (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Description 


Every line below the deleted line moves up, and the bottom line becomes blank. 
The current (y,x) coordinates of the cursor remain unchanged. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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delwin 

Deletes the specified window from memory. 
Format 

#include <curses.h> 

int delwin (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Description 


If the window being deleted contains a subwindow, the subwindow is invalidated. 
Delete subwindows before deleting their parent. The delwin function refreshes 
all windows covered by the deleted window. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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difftime 


difftime 

Computes the difference, in seconds, between the two times specified by the time1 

and time2 arguments. 
Format 

#include <time.h> 

double difftime (time_t time2, time_t timet): 
Arguments 

time2 

A time value of type time _t. 

time1 

A time value of type time t. 
Description 


The type time _t is defined in the <time.h> header file as follows: 
typedef unsigned long int time_t 


Return Value 


n time2 — timel in seconds expressed as a double. 
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dirname 


Format 


Reports the parent directory name of a file pathname. 


#include <libgen.h> 


char *dirname (char *path): 


Function Variants 


Argument 


Description 


The dirname function has variants named dirname32 and dirnameé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


path 
The file pathname. 


The dirname function takes a pointer to a character string that contains a UNIX 
pathname and returns a pointer to a string that is a pathname of the parent 
directory of that file. Trailing slash (/) characters in the path are not counted as 
part of the path. 


This function returns a pointer to the string "." (dot), when the path argument: 
e Does not contain a slash (/). 

e Isa NULL pointer. 

e Points to an empty string. 

The dirname function can modify the string pointed to by the path argument. 


The dirname and basename functions together yield a complete pathname. 
The expression dirname(path) obtains the pathname of the directory where 
basename(path) is found. 


See also basename. 


Return Values 


x A pointer to a string that is the parent directory 
of the path argument. 

ne The path argument: 

e Does not contain a slash (/). 

e Is a NULL pointer. 


e Points to an empty string. 
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Example 


Using the dirname function, the following example reads a pathname, changes 
the current working directory to the parent directory, and opens a file. 


char path [MAXPATHLEN], *pathcopy; 
int fd; 


fgets(path, MAXPATHLEN, stdin); 
pathcopy = strdup (path) ; 
chdir (dirname (pathcopy) ) ; 

) ag 


fd = open(basename (path), O RDONLY) ; 
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div 

Returns the quotient and the remainder after the division of its arguments. 
Format 

#include <stdlib.h> 

div_t div (int numer, int denom): 
Arguments 

numer 

A numerator of type int. 

denom 

A denominator of type int. 
Description 


The type div_t is defined in the standard header file <stdlib.h> as follows: 
typedef struct 


int quot, rem; 
} div t; 
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diclose 


Format 


Argument 


Description 
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Deallocates the address space for a shared library. 


#include <dlfcn.h> 


void diclose (void *handle); 


handle 
Pointer to the shared library. 


The diclose function deallocates the address space allocated by the HP C RTL 
for the handle. 


There is no way on OpenVMS systems to unload a shareable image dynamically 
loaded by the LIB$FIND_IMAGE_SYMBOL routine, which is the routine called 
by the dlsym function. In other words, there is no way on OpenVMS systems to 
release the address space occupied by the shareable image brought into memory 
by dlsym. 


dlerror 


dlerror 


Returns a string describing the last error that occurred from a call to dlopen, 
dlclose, or dlsym. 


Format 
#include <dlfcn.h> 


char “dlerror (void); 


Return Value 


x A string describing the last error that occurred 
from a call to dlopen, dlclose, or dlsym. 
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dlopen 


Format 


Arguments 


Description 


Provides an interface to the dynamic library loader to allow shareable images to 
be loaded and called at run time. 


#include <dlfcn.h> 


void “dlopen (char “pathname, int mode); 


pathname 
The name of the shareable image. This name is saved for subsequent use by the 
dlsym function. 


mode 
This argument is ignored on OpenVMS systems. 


The dlopen function provides an interface to the dynamic library loader to allow 
shareable images to be loaded and called at run time. 


This function does not load a shareable image but rather saves its pathname 
argument for subsequent use by the dlsym function. dlsym is the function 
that actually loads the shareable image through a call to LIB$FIND_IMAGE_ 
SYMBOL. 


The pathname argument of the dlopen function must be the name of the 
shareable image. This name is passed as-is by the dlsym function to the 
LIB$FIND_IMAGE_SYMBOL routine as the filename argument. No image- 
name argument is specified in the call to LIB$FIND_IMAGE_SYMBOL, so 
default file specification of SYS$SHARE:.EXE is applied to the image name. 


The dlopen function returns a handle that is used by a dlsym or diclose call. If 
an error occurs, a NULL pointer is returned. 


Return Values 
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x A handle to be used by a dlsym or diclose call. 
NULL Indicates an error. 


disym 


disym 


Format 


Arguments 


Description 


Returns the address of the symbol name found in a shareable image. 


#include <dlfcn.h> 


void *“disym (void *handle, char *name); 


handle 
Pointer to the shareable image. 


name 
Pointer to the symbol name. 


The dlsym function returns the address of the symbol name found in the 
shareable image corresponding to handle. If the symbol is not found, a NULL 
pointer is returned. 


As of OpenVMS Version 7.3-2, library symbols containing lowercase characters 
can be loaded using the disym function. More generally, the functions that 
dynamically load libraries (dlopen, dlsym, dlclose, dlerror) are enhanced to 
provide the following capabilities: 


e Support for libraries with mixed-case symbol names 
e Ability to pass a full file path to dlopen 


e Validation of the specified library name 


Return Values 


x Address of the symbol name found. 
NULL Indicates that the symbol was not found. 
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drand48 


Format 


Description 


Generates uniformly distributed pseudorandom-number sequences. Returns 
48-bit, nonnegative, double-precision floating-point values. 


#include <stdlib.h> 
double drand48 (void); 


The drand48 function generates pseudorandom numbers using the linear 
congruential algorithm and 48-bit integer arithmetic. 


It returns nonnegative, double-precision, floating-point values uniformly 
distributed over the range of y values such that 0.0 < y < 1.0. 


Before you call drand48, use either srand48, seed48, or 1cong48 to initialize the 
random-number generator. You must initialize prior to invoking the drand48 
function because it stores the last 48-bit Xi generated into an internal buffer. 
(Although it is not recommended, constant default initializer values are supplied 
automatically if the drand48, lrand48, or mrand48 functions are called without 
first calling an initialization function.) 


The drand48 function works by generating a sequence of 48-bit integer values, Xi, 
according to the linear congruential formula: 

Xn+1 = (aXn+c)mod m n >= 0 
The argument m equals 248, so 48-bit integer arithmetic is performed. Unless you 
invoke lcong48, the multiplier value a and the addend value c are: 


a 
Cc 


5DEECE66D16 = 2736731631558 
B16 = 138 


The values returned by drand48 are computed by first generating the next 
48-bit Xi in the sequence. Then the appropriate bits, according to the type of 
returned data item, are copied from the high-order (most significant) bits of Xi 
and transformed into the returned value. 


See also srand48, seed48, lcong48, lrand48, and mrand48. 


Return Value 


REF-146 


n A nonnegative, double-precision, floating-point 
value. 


dup, dup2 


dup, dup2 


Format 


Arguments 


Description 


Allocate a new descriptor that refers to a file specified by a file descriptor returned 
by open, creat, or pipe. 


#include <unistd.h> 
int dup (int file_desct); 
int dup2 (int file_desc?, int file_desc2); 


file_desc1 
The file descriptor being duplicated. 


file_desc2 
The new file descriptor to be assigned to the file designated by file_desc1. 


The dup function causes a previously unallocated descriptor to refer to its 
argument, while the dup2 function causes its second argument to refer to the 
same file as its first argument. 


The argument file_desc1 is invalid if it does not describe an open file; file_desc2 is 
invalid if the new file descriptor cannot be allocated. If file_desc2 is connected to 
an open file, that file is closed. 


Return Values 


n The new file descriptor. 


-1 Indicates that an invalid argument was passed 
to the function. 


REF-147 


[noJecho 


[no]echo 


Set the terminal so that characters may or may not be echoed on the terminal 
screen. This mode of single-character input is only supported with Curses. 


Format 
#include <curses.h> 


void echo (void); 


void noecho (void); 


Description 


The noecho function may be helpful when accepting input from the terminal 
screen with wgetch and wgetstr; it prevents the input characters from being 
written onto the screen. 
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ecvt 


Format 


Arguments 


Description 


Converts its argument to a null-terminated string of ASCII digits and returns the 
address of the string. The string is stored in a thread-specific memory location 
created by the HP C RTL. 


#include <stdlib.h> 


char *ecvt (double value, int ndigits, int *decpt, int *sign); 


value 
An object of type double that is converted to a null-terminated string of ASCII 
digits. 


ndigits 
The number of ASCII digits to be used in the converted string. 


decpt 

The position of the decimal point relative to the first character in the returned 
string. A negative int value means that the decimal point is decpt number of 
spaces to the left of the returned digits (the spaces being filled with zeros). A 0 
value means that the decimal point is immediately to the left of the first digit in 
the returned string. 


sign 

An integer value that indicates whether the value argument is positive or 
negative. If value is negative, the function places a nonzero value at the address 
specified by sign. Otherwise, the function assigns 0 to the address specified by 
sign. 


The ecvt function converts value to a null-terminated string of length ndigits, 
and returns a pointer to it. The resulting low-order digit is rounded to the correct 
digit for outputting ndigits digits in C E-format. The decpt argument is assigned 
the position of the decimal point relative to the first character in the string. 


Repeated calls to the ecvt function overwrite any existing string. 


The ecvt, fcvt, and gcvt functions represent the following special values 
specified in the IEEE Standard for floating-point arithmetic: 


Value Representation 
Quiet NaN NaNQ 
Signalling NaN NaNS 
+Infinity Infinity 
—Infinity —Infinity 


The sign associated with each of these values is stored into the sign argument. In 
IEEE floating-point representation, a value of 0 (zero) can be positive or negative, 
as set by the sign argument. 
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See also gcvt and fevt. 


Return Value 


x The value of the converted string. 


REF-150 


encrypt 


encrypt 


Format 


Argument 


Description 


Encrypts a string using the key generated by the setkey function. 


#include <unistd.h> 
#include <stdlib.h> 
void encrypt (char “block{64], int edflag;) 


block 
A character array of length 64 containing 0s and 1s. 


edflag 
An integer. If edflag is 0, the argument is encrypted; if nonzero, it is decrypted. 


The encrypt function encrypts a string using the key generated by the setkey 
function. 


The first argument to encrypt is a character array of length 64 containing Os and 
1s. The argument array is modified in place to a similar array representing the 
bits of the argument after having been subjected to the DES algorithm using the 
key set by setkey. 


The second argument, edflag, determines whether the first argument is encrypted 
or decrypted: if edflag is 0, the first argument array is encrypted; if nonzero, it is 
decrypted. 


No value is returned. 


See also crypt and setkey. 


Return Value 


pointer Pointer to the encrypted password. 


REF-151 


endgrent (ipa, 164) 


endgrent (aipia, 164 


Closes the group database when processing is complete. 


Format 
#include <grp.h> 


void endgrent (void); 


Description 
The endgrent function closes the group database. 


This function is always successful. No value is returned, and errno is not set. 
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endpwent 
Closes the user database and any private stream used by getpwent. 


Format 
#include <pwd.h> 


void endpwent (void); 


Description 


The endpwent function closes the user database and any private stream used by 
getpwent. 


No value is returned. If an I/O error occurred, the function sets errno to EIO. 


See also getpwent, getpwuid, getpwnam, and setpwent. 
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endwin 


endwin 
Clears the terminal screen and frees any virtual memory allocated to Curses data 
structures. 
Format 
#include <curses.h> 
void endwin (void): 
Description 


A program that calls Curses functions must call the endwin function before 
exiting to restore the previous environment of the terminal screen. 
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erand48 


erand48 


Format 


Argument 


Description 


Generates uniformly distributed pseudorandom-number sequences. Returns 
48-bit nonnegative, double-precision, floating-point values. 


#include <stdlib.h> 
double erand48 (unsigned short int xsubi/3)) 


xsubi 
An array of three short ints, which form a 48-bit integer when concatentated 
together. 


The erand48 function generates pseudorandom numbers using the linear 
congruential algorithm and 48-bit integer arithmetic. 


It returns nonnegative, double-precision, floating-point values uniformly 
distributed over the range of y values, such that 0.0 < y < 1.0. 


The erand48 function works by generating a sequence of 48-bit integer values, Xz, 
according to the linear congruential formula: 


Xn+1 = (aXn+c)mod m n >= 0 


The argument m equals 2*®, so 48-bit integer arithmetic is performed. Unless you 
invoke the lcong48 function, the multiplier value a and the addend value c are: 


a 
Cc 


5DEECE66D16 = 2736731631558 
B16 = 13g 


The erand48 function requires that the calling program pass an array as the 
xsubi argument. For the first call, the array must be initialized to the value 
of the pseudorandom-number sequence. Unlike the drand48 function, it is not 
necessary to call an initialization function prior to the first call. 


By using different arguments, the erand48 function allows separate modules of 
a large program to generate several independent sequences of pseudorandom 
numbers; for example, the sequence of numbers that one module generates does 
not depend upon how many times the function is called by other modules. 


Return Value 


n A nonnegative, double-precision, floating-point 
value. 


REF-155 


[w]erase 


[w]erase 
Erases the window by painting it with blanks. The erase function acts on the 
stdscr window. 
Format 
#include <curses.h> 
int erase( ); 
int werase (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Description 


Both the erase and werase functions leave the cursor at the current position on 
the terminal screen after completion; they do not return the cursor to the home 
coordinates of (0,0). 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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erf 


Format 


Argument 


Description 


Returns the error function of its argument. 


#include <math.h> 

double erf (double x); 

float erff (float x); (Alpha, 164) 

long double erfl (long double x); (Alpha, 164) 
double erfc (double x); (Alpha, 164) 

float erfcf (float x); (Alpha, 164) 


long double erfcl (long double x); (Alpha, 164) 


x 
A radian expressed as a real number. 


The erf functions return the error function of x, where erf(x), erff(x), and 
erfl(x) equal 2/sqrt(z) times the area under the curve e**(—t**2) between 0 and 
x. 


The erfc functions return (1.0 — erf(x)). The erfc function can result in an 
underflow as x gets large. 


Return Values 


x The value of the error function (erf) or 
complementary error function (erfc). 

NaN x is NaN; errno is set to EDOM. 

0 Underflow occurred; errno is set to ERANGE. 
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execl 


execl 


Format 


Arguments 


Description 
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Passes the name of an image to be activated in a child process. This function is 
nonreentrant. 


#include <unistd.h> 


int execl (const char *file_spec, const char *argO,... , (char *)0); @so POSIX-1) 
int exec! (char *file_spec, ... ); (Compatability) 
file_spec 


The full file specification of a new image to be activated in the child process. 


arg), ... 
A sequence of pointers to null-terminated character strings. 


If the POSIX-1 format is used, at least one argument must be present and 

must point to a string that is the same as the new process file name (or its last 
component). (This pointer can also be the NULL pointer, but then execle would 
accomplish nothing.) The last pointer must be the NULL pointer. This is also the 
convention if the compatibility format is used. 


To understand how the exec functions operate, consider how the OpenVMS 
system calls any HP C program, as shown in the following syntax: 


int main (int argc, char *argv[ J, char “envp/ )); 


The identifier argc is the argument count; argu is an array of argument strings. 
The first member of the array (argu[0]) contains the name of the image. The 
arguments are placed in subsequent elements of the array. The last element of 
the array is always the NULL pointer. 


An exec function calls a child process in the same way that the run-time system 
calls any other HP C program. The exec functions pass the name of the image to 
be activated in the child; this value is placed in arguv[0]. However, the functions 

differ in the way they pass arguments and environment information to the child: 


e Arguments can be passed in separate character strings (execl, execle, and 
execlp) or in an array of character strings (execv, execve, and execvp). 


e The environment can be explicitly passed in an array (execle and execve) or 
taken from the parent’s environment (execl, execv, execlp, and execvp). 


If vfork was called before invoking an exec function, then when the exec function 
completes, control is returned to the parent process at the point of the vfork call. 
If vfork was not called, the exec function waits until the child has completed 
execution and then exits the parent process. See vfork and Chapter 5 for more 
information. 


execl 


Return Value 


-1 Indicates failure. 
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execle 


execle 


Format 


Arguments 


Description 


Passes the name of an image to be activated in a child process. This function is 
nonreentrant. 


#include <unistd.h> 


int execle (char *file_spec, char *argO, ... , (char *)0, char *envp[]); aso Posrx-1) 
int execle (char *file_spec, ... ); (Compatability) 
file_spec 


The full file specification of a new image to be activated in the child process. 
arg), ... 
A sequence of pointers to null-terminated character strings. 


If the POSIX-1 format is used, at least one argument must be present and 

must point to a string that is the same as the new process file name (or its last 
component). (This pointer can also be the NULL pointer, but then execle would 
accomplish nothing.) The last pointer must be the NULL pointer. This is also the 
convention if the compatibility format is used. 


envp 
An array of strings that specifies the program’s environment. Each string in enup 
has the following form: 


name = value 


The name can be one of the following names and the value is a null-terminated 
string to be associated with the name: 


e HOME—Your login directory 

e TERM —tThe type of terminal being used 

e PATH—The default device and directory 

e USER—The name of the user who initiated the process 
The last element in envp must be the NULL pointer. 


When the operating system executes the program, it places a copy of the current 
environment vector (enup) in the external variable environ. 


See execl for a description of how the exec functions operate. 


Return Value 
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—1 Indicates failure. 


execip 


execlip 


Format 


Arguments 


Description 


Passes the name of an image to be activated in a child process. This function is 
nonreentrant. 


#include <unistd.h> 


int execlp (const char *file_name, const char *arg0,... , (char *)0); @so POSIX-1) 
int execlp (char *file_name, ... ); (Compatability) 
file_name 


The file name of a new image to be activated in the child process. The device 
and directory specification for the file is obtained by searching the VAXC$PATH 
environment name. 


argn 

A sequence of pointers to null-terminated character strings. By convention, at 
least one argument must be present and must point to a string that is the same 
as the new process file name (or its last component). 


A sequence of pointers to strings. At least one pointer must exist to terminate 
the list. This pointer must be the NULL pointer. 


See execl for a description of how the exec functions operate. 


Return Value 


a1 Indicates failure. 
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execv 


Format 


Arguments 


Description 


Passes the name of an image to be activated in a child process. This function is 
nonreentrant. 


#include <unistd.h> 


int execv (char *file_spec, char “argv }); 


file_spec 
The full file specification of a new image to be activated in the child process. 


argv 

An array of pointers to null-terminated character strings. These strings 
constitute the argument list available to the new process. By convention, argv[0] 
must point to a string that is the same as the new process file name (or its last 
component). argu is terminated by a NULL pointer. 


See execl for a description of how the exec functions operate. 


Return Value 
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—1 Indicates failure. 


execve 


execve 


Format 


Arguments 


Description 


Passes the name of an image to be activated in a child process. This function is 
nonreentrant. 


#include <unistd.h> 


int execve (const char *file_spec, char “argv[], char *envp| )); 


file_spec 
The full file specification of a new image to be activated in the child process. 


argv 

An array of pointers to null-terminated character strings. These strings 
constitute the argument list available to the new process. By convention, argv[0] 
must point to a string that is the same as the new process file name (or its last 
component). argu is terminated by a NULL pointer. 


envp 
An array of strings that specifies the program’s environment. Each string in enup 
has the following form: 


name = value 


The name can be one of the following names and the value is a null-terminated 
string to be associated with the name: 


e HOME—Your login directory 

e TERM—tThe type of terminal being used 

e PATH—The default device and directory 

e USER—The name of the user who initiated the process 
The last element in envp must be the NULL pointer. 


When the operating system executes the program, it places a copy of the current 
environment vector (enup) in the external variable environ. 


See execl for a description of how the exec functions operate. 


Return Value 


—1 Indicates failure. 
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execvp 


Format 


Arguments 


Description 


Passes the name of an image to be activated in a child process. This function is 
nonreentrant. 


#include <unistd.h> 


int execvp (const char *file_name, char “argv[ }); 


file_name 

The file name of a new image to be activated in the child process. The device and 
directory specification for the file is obtained by searching the environment name 
VAXC$PATH. 


argv 

An array of pointers to null-terminated character strings. These strings 
constitute the argument list available to the new process. By convention, argv[0] 
must point to a string that is the same as the new process file name (or its last 
component). argu is terminated by a NULL pointer. 


See execl for a description of how the exec functions operate. 


Return Value 
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—1 Indicates failure. 


exit, exit 


exit, exit 


Format 


Argument 


Description 


Terminate execution of the program from which they are called. These functions 
are nonreentrant. 


#include <stdlib.h> 
void exit (int status); 
#include <unistd.h> 


void _exit (int status); 


status 
For non-POSIX behavior, a status value of EXIT_SUCCESS (1), EXIT_FAILURE 
(2), or a number from 3 to 255, as follows: 


e A status value of 0, 1 or EXIT_SUCCESS is translated to the OpenVMS 
SS$_NORMAL status code to return the OpenVMS success value. 


e A status value of 2 or EXIT_FAILURE is translated to an error-level exit 
status. The status value is passed to the parent process. 


e Any other status value is left the same. 
For POSIX behavior: 


e A status value of 0 is translated to the OpenVMS SS$_NORMAL status code 
to return the OpenVMS success value. 


e Any other status is returned to the parent process as an OpenVMS message 
symbol with facility set to C, severity set to success, and with the status in 
the message number field. For more information on the format of message 
symbols, see "message code" in the HP OpenVMS Command Definition, 
Librarian, and Message Utilities Manual. 


To get POSIX behavior, include <unistd.h> and compile with the _POSIX_EXIT 
feature-test macro set (either with /DEFINE=_POSIX_EXIT, or with #define 
_POSIX_EXIT at the top of your file, before any file inclusions). This behavior is 
available only on OpenVMS Version 7.0 and higher systems. 


If the process was invoked by DCL, the status is interpreted by DCL, and a 
message is displayed. 


If the process was a child process created using vfork or an exec function, then 
the child process exits and control returns to the parent. The two functions are 
identical; the exit function is retained for reasons of compatibility with VAX C. 


The exit and exit functions make use of the $EXIT system service. If your 
process is being invoked by the RUN command using any of the hibernation and 
scheduled wakeup qualifiers, the process might not correctly return to hibernation 
state when an exit or exit call is made. 
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exit, exit 


The C compiler command-line qualifier /[NO]MAIN=POSIX_EXIT can be used to 
direct the compiler to call _posix_exit instead of exit when returning from 
main. The default is /NOMAIN. 


Note 


EXIT_SUCCESS and EXIT_FAILURE are portable across any ANSI C 
compiler to indicate success or failure. On OpenVMS systems, they are 
mapped to OpenVMS condition codes with the severity set to success or 
failure, respectively. Values in the range of 3 to 255 can be used by a child 
process to communicate a small amount of data to the parent. The parent 
retreives this data using the wait, wait3, wait4, or waitpid functions. 
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exp 


exp 


Format 


Argument 


Description 


Returns the base e raised to the power of the argument. 


#include <math.h> 

double exp (double x); 

float expf (float x); (Alpha, 164) 

long double exp! (long double x); (Aipha, 164) 
double expm1 (double x); (Alpha, 164) 

float expmif (float x); (Alpha, 164) 


long double expm1! (long double x); (Alpha, 164) 


4 
A real value. 


The exp functions compute the value of the exponential function, defined as e**x, 
where e is the constant used as a base for natural logarithms. 


The expm1 functions compute exp(x) — 1 accurately, even for tiny x. 


If an overflow occurs, the exp functions return the largest possible floating-point 
value and set errno to ERANGE. The constant HUGE_VAL is defined in the 
<math.h> header file to be the largest possible floating-point value. 


Return Values 


x The exponential value of the argument. 
HUGE_VAL Overflow occurred; errno is set to ERANGE. 
0 Underflow occurred; errno is set to ERANGE. 
NaN x is NaN; errno is set to EDOM. 
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EXP2 (Alpha, 164) 


EXP2 daipia, 164) 


Returns the value of 2 raised to the power of the argument. 


Format 

#include <math.h> 

double exp2 (double x); 

float exp2f (float x); 

long double exp2I (long double x); ) 
Argument 

x 

A real value. 
Description 


The exp2 functions compute the base-2 exponential of x. 


If an overflow occurs, the exp functions return the largest possible floating-point 
value and set errno to ERANGE. The constant HUGE_VAL is defined in the 
<math.h> header file to be the largest possible floating-point value. 


Return Values 


n Dia op 

HUGE_VAL Overflow occurred; errno is set to ERANGE. 

1 x is +0 or —0; errno is set to ERANGE. 

0 x is —Inf or underflow occurred; errno is set to 
ERANGE. 

x x is +Inf; errno is set to ERANGE. 

NaN x is NaN; errno is set to EDOM. 
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fabs 


fabs 

Returns the absolute value of its argument. 
Format 

#include <math.h> 

double fabs (double x); 

float fabsf (float x); (Alpha, 164) 

long double fabs! (long double x); (Alpha, 164) 
Argument 


4 
A real value. 


Return Value 


x The absolute value of the argument. 
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fchmod 


fchmod 

Changes file access permissions. 
Format 

#include <stat.h> 

int fchmod (int fildes, mode_t mode); 
Arguments 

fildes 

An open file descriptor. 

mode 

The bit pattern that determines the access permissions. 
Description 


The fchmod function is equivalent to the chmod function, except that the file 
whose permissions are changed is specified by a file descriptor (fi/des) rather than 
a filename. 


Return Values 


0 Indicates that the mode is successfully changed. 
—1 Indicates that the change attempt has failed. 
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fchown 


fchown 


Changes the owner and group of a file. 


Format 


#include <unistd.h> 


int fchown (int fildes, uid_t owner, gid_t group); 


Arguments 


fildes 
An open file descriptor. 


owner 


A user ID corresponding to the new owner of the file. 


group 


A group ID corresponding to the group of the file. 


Description 


The fchown function has the same effect as chown except that the file whose 
owner and group are to be changed is specified by the file descriptor fildes. 


Return Values 


0 
-1 


Indicates success. 


Indicates failure. The function sets errno to one 
of the following values: 


The fchown function will fail if: 


EBADF -— The fildes argument is not an open 
file descriptor. 


EPERM — The effective user ID does not 
match the owner of the file, or the process 
does not have appropriate privilege. 


EROFS — The file referred to by fildes resides 
on a read-only file system. 


The fchown function may fail if: 


EINVAL — The owner or group ID is not a 
value supported by the implementation. 


EIO — A physical I/O error has occurred. 


EINTR — The fchown function was 
interrupted by a signal that was caught. 
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fclose 


fclose 


Format 


Argument 


Description 


Closes a file by flushing any buffers associated with the file control block and 
freeing the file control block and buffers previously associated with the file 
pointer. 


#include <stdio.h> 
int fclose (FILE *file_ptr); 


file_ptr 
A pointer to the file to be closed. 


When a program terminates normally, the fclose function is automatically called 
for all open files. 


The fclose function tries to write buffered data by using an implicit call to 
fflush. 


If the write fails (because the disk is full or the user’s quota is exceeded, 

for example), fclose continues executing. It closes the OpenVMS channel, 
deallocates any buffers, and releases the memory associated with the file 
descriptor (or FILE pointer). Any buffered data is lost, and the file descriptor (or 
FILE pointer) no longer refers to the file. 


If your program needs to recover from errors when flushing buffered data, it 
should make an explicit call to fsync (or fflush) before calling fclose. 


Return Values 
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0 Indicates success. 


EOF Indicates that the file control block is not 
associated with an open file. 


fentl 


fentl 


Format 


Arguments 


Description 


Performs controlling operations on an open file. 


#include <sys/types.h> 

#include <unistd.h> 

#include <fcntl.h> 

int fentl (int file_desc, int request [, int arg]); 


int fentl (int file_desc, int request [, struct flock *arg]); 


file_desc 
An open file descriptor obtained from a successful open, fcnt1, or pipe function. 


request 
The operation to be performed. 


arg 
A variable that depends on the value of the request argument. 


For a request of F_.DUPFD, F_SETFD, or F_SETFL, specify arg as an int. 
For a request of F_ GETFD and F_GETFL, do not specify arg. 


For a request of F_GETLK, F_SETLK, or F_SETLKW specify arg as a pointer to 
a flock structure. 


The fcnt1 function performs controlling operations on the open file specified by 
the file_desc argument. 


The values for the request argument are defined in the header file <fcnt1l.h>, and 
include the following: 


F_DUPFD Returns a new file descriptor that is the lowest numbered 
available (that is, not already open) file descriptor greater 
than or equal to the third argument (arg) taken as an 
integer of type int. 


The new file descriptor refers to the same file as the original 
file descriptor (file_desc). The FD CLOEXEC flag associated 
with the new file descriptor is cleared to keep the file open 
across calls to one of the exec functions. 
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F_GETFD 


F_SETFD 


F_GETFL 


F_SETFL 


The following two calls are equivalent: 
fid = dup(file desc) ; 


fid = fentl(file desc, F_DUPFD, 0); 
Consider the following call: 


fid = dup2(file desc, arg) ; 


It is similar (but not equivalent) to: 


close (arg) ; 

fid = fentl(file desc, F _DUPFD, arg); 

Gets the value of the close-on-exec flag associated with the 
file descriptor file_desc. File descriptor flags are associated 
with a single file descriptor and do not affect other file 
descriptors that refer to the same file. The arg argument 
should not be specified. 


Sets the close-on-exec flag associated with file_desc to the 
value of the third argument, taken as type int. 

If the third argument is 0, the file remains open across the 
exec functions, which means that a child process spawned 
by the exec function inherits this file descriptor from the 
parent. 

If the third argument is FD_CLOEXEC, the file is closed on 
successful execution of the next exec function, which means 
that the child process spawned by the exec function will 
not inherit this file descriptor from the parent. 


Gets the file status flags and file access modes, defined in 
<fcntl.h>, for the file description associated with file_desc. 
The file access modes can be extracted from the return 
value using the mask O_ACCMODE, which is defined in 
<fcntl.h>. File status flags and file access modes are 
associated with the file description and do not affect other 
file descriptors that refer to the same file with different 
open file descriptions. 


Sets the file status flags, defined in <fcnt1.h>, for the file 
description associated with file_desc from the corresponding 
bits in the third argument, arg, taken as type int. Bits 
corresponding to the file access mode and the file creation 
flags, as defined in <fcntl.h>, that are set in arg are 
ignored. If any bits in arg other than those mentioned here 
are changed by the application, the result is unspecified. 


fentl 


Note: The only status bit recognized is O_APPEND. 
Support for O_APPEND is not standard-compliant. The 
X/Open standard states that "File status flags and file 
access modes are associated with the file description and do 
not affect other file descriptors that refer to the same file 
with different open file descriptions." However, because the 
append bit is stored in the FCB, all file descriptors using 
the same FCB are using the same append flag, so that 
setting this flag with fcntl(F SETFL) will affect all files 
sharing the FCB; that is, all files duplicated from the same 
file descriptor. 


Record Locking Requests 


F_GETLK 


F_SETLK 


F_SETLKW 


File Locking 


Gets the first lock that blocks the lock description pointed 
to by the arg parameter, taken as a pointer to type 
struct flock. The information retrieved overwrites the 
information passed to the fcnt1 function in the flock 
structure. If no lock is found that would prevent this lock 
from being created, then the structure is left unchanged 
except for the lock type, which is set to F_UNLCK. 


Sets or clears a file segment lock according to the lock 
description pointed to by arg, taken as a pointer to type 
struct flock. F_SETLK is used to establish shared locks 
(F_RDLCK), or exclusive locks (F_WRLCK), as well as 
remove either type of lock (F_UNLCK). If a shared (read) 
or exclusive (write) lock cannot be set, the fcnt1 function 
returns immediately with a value of —1. 


An unlock (F_UNLCK) request in which the /_len of the 
flock structure is nonzero and the offset of the last byte 
of the requested segment is the maximum value for an 
object of type off t, when the process has an existing lock 
in which /_len is 0 and which includes the last byte of the 
requested segment, is treated as a request to unlock from 
the start of the requested segment with an /_len equal to 
0. Otherwise, an unlock (F_UNLCK) request attempts to 
unlock only the requested file. 


Same as F_SETLK except that if a shared or exclusive lock 
is blocked by other locks, the process will wait until it is 
unblocked. If a signal is received while fcnt1 is waiting for 
a region, the function is interrupted, —1 is returned, and 
errno is set to EINTR. 


The C RTL supports byte-range file locking using the F_GETLK, F_SETLK, 
and F_SETLKW commands of the fcnt1 function, as defined in the X/Open 
specification. Byte-range file locking is supported across OpenVMS clusters. You 
can only use offsets that fit into 32-bit unsigned integers. 


When a shared lock is set on a segment of a file, other processes on the cluster are 
able to set shared locks on that segment or a portion of it. A shared lock prevents 
any other process from setting an exclusive lock on any portion of the protected 
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area. A request for a shared lock fails if the file descriptor was not opened with 
read access. 


An exclusive lock prevents any other process on the cluster from setting a shared 
lock or an exclusive lock on any portion of the protected area. A request for an 
exclusive lock fails if the file descriptor was not opened with write access. 


The flock structure describes the type (/_type), starting offset (1_whence), relative 
offset (/_start), size (l_len) and process ID (l_pid) of the segment of the file to be 
affected. 


The value of /_whence is set to SEEK_SET, SEEK CUR or SEEK_END, to 
indicate that the relative offset /_start bytes is measured from the start of the 
file, from the current position, or from the end of the file, respectively. The value 
of /_len is the number of consecutive bytes to be locked. The /_len value may be 
negative (where the definition of off t permits negative values of /_len). The 
l_pid field is only used with F_GETLK to return the process ID of the process 
holding a blocking lock. After a successful F_GETLK request, the value of l_ 
whence becomes SEEK_SET. 


If /_len is positive, the area affected starts at /_start and ends at /_start + l_len 

- 1. If l_len is negative, the area affected starts at /_start + /_len and ends at 
l_start - 1. Locks may start and extend beyond the current end of a file, but may 
not be negative relative to the beginning of the file. If /_len is set to 0 (zero), a 
lock may be set to always extend to the largest possible value of the file offset 
for that file. If such a lock also has /_start set to 0 (zero) and l_whence is set to 
SEEK_SET, the whole file is locked. 


Changing or unlocking a portion from the middle of a larger locked segment 
leaves a smaller segment at either end. Locking a segment that is already locked 
by the calling process causes the old lock type to be removed and the new lock 
type to take effect. 


All locks associated with a file for a given process are removed when a file 
descriptor for that file is closed by that process or the process holding that file 
descriptor terminates. Locks are not inherited by a child process. 


If the request argument is F_SETLKW, the lock is blocked by some lock from 
another process, and putting the calling process to sleep to wait for that lock to 
become free would cause a deadlock, then the application will hang. 


Return Values 
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n Upon successful completion, the value returned 
depends on the value of the request argument as 
follows: 


e F _DUPFD — Returns a new file descriptor. 
e F GETFD — Returns FD_CLOEXEC or 0. 


° F SETFD, F_GETLK, F_SETLK, F UNLCK — Return 
a value other than —1. 


fentl 


—1 Indicates that an error occurred. The function 
sets errno to one of the following values: 


EACCES — The request argument is F_ 
SETLK; the type of lock (/_type) is a shared 
(F_RDLCK) or exclusive (F_WRLCK) lock, 
and the segment of a file to be locked is 
already exclusive-locked by another process; 
or the type is an exclusive (F_WRLCK) lock 
and the some portion of the segment of a 
file to be locked is already shared-locked or 
exclusive-locked by another process. 


EBADF -— The file_desc argument is not 

a valid open file descriptor and the arg 
argument is negative or greater than or 
equal to the per-process limit. 

The request parameter is F_SETLK or F_ 
SETLKW, the type of lock (/_type) is a shared 
lock (F_RDLCK), and file_desc is not a valid 
file descriptor open for reading. 

The type of lock (/_type) is an exclusive lock 
(F_WRLCK), and file_desc is not a valid file 
descriptor open for writing. 


EFAULT — The arg argument is an invalid 
address. 


EINVAL — The request argument is F_DUPFD 
and arg is negative or greater than or equal 
to OPEN_MAX. 

Either the OPEN_MAX value or the per- 
process soft descriptor limit is checked. 

An illegal value was provided for the request 
argument. 

The request argument is F_GETLK, F_ 
SETLK, or F_SETLKW and the data pointed 
to by arg is invalid, or file_desc refers to a file 
that does not support locking. 


EMFILE — The request argument is F_DUPFD 
and too many or OPEN_MAX file descriptors 
are currently open in the calling process, or 
no file descriptors greater than or equal to 
arg are available. 

Either the OPEN_MAX value or the per- 
process soft descriptor limit is checked. 
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EOVERFLOW -— One of the values to be 
returned cannot be represented correctly. 
The request argument is F_GETLK, F_ 
SETLK, or F_SETLKW and the smallest 
or, if /_len is nonzero, the largest offset of 
any byte in the requested segment cannot 
be represented correctly in an object of type 
off t. 


EINTR — The request argument is F_ 
SETLKW, and the function was interrupted 
by a signal. 


ENOLCK -— The request argument is F_ 
SETLK or F_SETLKW, and satisfying 
the lock or unlock request would exceed 
the configurable system limit of NLOCK_ 
RECORD. 


ENOMEM - The system was unable to 
allocate memory for the requested file 
descriptor. 


fevt 


fevt 


Format 


Arguments 


Description 


Converts its argument to a null-terminated string of ASCII digits and returns the 
address of the string. The string is stored in a thread-specific location created by 
the HP C RTL. 


#include <stdlib.h> 


char *fevt (double value, int ndigits, int *decpt, int *sign); 


value 
An object of type double that is converted to a null-terminated string of ASCII 
digits. 


ndigits 
The number of ASCII digits after the decimal point to be used in the converted 
string. 


decpt 

The position of the decimal point relative to the first character in the returned 
string. The returned string does not contain the actual decimal point. A negative 
int value means that the decimal point is decpt number of spaces to the left of 
the returned digits (the spaces are filled with zeros). A 0 value means that the 
decimal point is immediately to the left of the first digit in the returned string. 


sign 

An integer value that indicates whether the value argument is positive or 
negative. If value is negative, the fcvt function places a nonzero value at the 
address specified by sign. Otherwise, the functions assign 0 to the address 
specified by sign. 


The fcvt function converts value to a null-terminated string and returns a 
pointer to it. The resulting low-order digit is rounded to the correct digit for 
outputting ndigits digits in C F-format. The decpt argument is assigned the 
position of the decimal point relative to the first character in the string. 


In C F-format, ndigits is the number of digits desired after the decimal point. 
Very large numbers produce a very long string of digits before the decimal point, 
and ndigit of digits after the decimal point. For large numbers, it is preferable to 
use the gcvt or ecvt function so that E-format is used. 


Repeated calls to the fcvt function overwrite any existing string. 


The ecvt, fcvt, and gcvt functions represent the following special values 
specified in the IEEE Standard for floating-point arithmetic: 


Value Representation 
Quiet NaN NaNQ 
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Value Representation 
Signalling NaN NaNS 
+Infinity Infinity 
—Infinity —Infinity 


The sign associated with each of these values is stored into the sign argument. In 
IEEE floating-point representation, a value of 0 (zero) can be positive or negative, 
as set by the sign argument. 


See also gcvt and ecvt. 


Return Value 


x A pointer to the converted string. 
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fdim (ipna, 164 


fdim (Alpha, 164) 


Determines the positive difference between its arguments. 


Format 

#include <math.h> 

double fdim (double x, double y); 

float fdimf (float x, float y); 

long double fdiml (long double x, long double y); 
Argument 

x 

A real value. 

A real value. 
Description 


The fdim functions determine the positive difference between their arguments. If 
x is greater than y, x - y is returned. If x is less than or equal to y, +0 is returned. 


Return Values 


n Upon success, the positive difference value. 

HUGE_VAL If x - y is positive and overflows; errno is set to 
ERANGE. 

0 If x - y is positive and underflows; errno is set to 
ERANGE. 

NaN x or y is NaN; errno is set to EDOM. 
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fdopen 


Format 


Arguments 


Description 


Associates a file pointer with a file descriptor returned by an open, creat, dup, 
dup2, or pipe function. 


#include <stdio.h> 


FILE “fdopen (int file_desc, char *a_mode); 


file_desc 
The file descriptor returned by open, creat, dup, dup2, or pipe. 


a_mode 

The access mode indicator. See the fopen function for a description. Note that 
the access mode specified must agree with the mode used to originally open the 
file. This includes binary/text access mode ("b" mode on fdopen and the "ctx=bin" 
option on creat or open). 


The fdopen function allows you to access a file, originally opened by one of 

the UNIX I/O functions, with Standard I/O functions. Ordinarily, a file can be 
accessed by either a file descriptor or by a file pointer, but not both, depending on 
the way you open it. For more information, see Chapters 1 and 2. 


Return Values 
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pointer Indicates that the operation has succeeded. 
NULL Indicates that an error has occurred. 


feof 


feof 

Tests a file to see if the end-of-file has been reached. 
Format 

#include <stdio.h> 

int feof (FILE *file_ptr); 
Argument 


file_ptr 
A file pointer. 


Return Values 


nonzero integer Indicates that the end-of-file has been reached. 
0 Indicates that the end-of-file has not been 
reached. 


REF-183 


feof_unlocked (ipna, 164) 


feof_unlocked «ipia, 164 


Format 


Argument 


Description 


Same as feof, except used only within a scope protected by flockfile and 
funlockfile. 


#include <stdio.h> 
int feof_unlocked (FILE *file_ptn); 


file_ptr 
A file pointer. 


The reentrant version of the feof function is locked against multiple threads 
calling it simultaneously. This incurs overhead to ensure integrity of the stream. 
The unlocked version of this call, feof unlocked can be used to avoid the 
overhead. The feof unlocked function is functionally identical to the feof 
function, except that it is not required to be implemented in a thread-safe 
manner. The feof unlocked function can be safely used only within a scope that 
is protected by the flockfile and funlockfile functions used as a pair. The 
caller must ensure that the stream is locked before feof unlocked is used. 


See also flockfile, ftrylockfile, and funlockfile. 


Return Values 
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nonzero integer Indicates end-of-file has been reached. 
0 Indicates end-of-file has not been reached. 


ferror 


ferror 

Returns a nonzero integer if an error occurred while reading or writing a file. 
Format 

#include <stdio.h> 

int ferror (FILE *file_ptr); 
Argument 


file_ptr 
A file pointer. 


Description 


A call to ferror continues to return a nonzero integer until the file is closed or 
until clearerr is called. 


Return Values 


0 Indicates success. 
nonzero integer Indicates that an error has occurred. 
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ferror_unlocked (ipia, 164 


ferror_unlocked aipic, 164 


Format 


Argument 


Description 


Same as ferror, except used only within a scope protected by flockfile and 
funlockfile. 


#include <stdio.h> 


int ferror_unlocked (FILE “*file_ptr); 


file_ptr 
A file pointer. 


The reentrant version of the ferror function is locked against multiple threads 
calling it simultaneously. This incurs overhead to ensure integrity of the stream. 
The unlocked version of this call, ferror_unlocked can be used to avoid the 
overhead. The ferror_unlocked function is functionally identical to the ferror 
function, except that it is not required to be implemented in a thread-safe 
manner. The ferror_unlocked function can be safely used only within a scope 
that is protected by the flockfile and funlockfile functions used as a pair. The 
caller must ensure that the stream is locked before ferror_unlocked is used. 


See also flockfile, ftrylockfile, and funlockfile. 


Return Values 
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0 Indicates success. 


nonzero integer Indicates that an error has occurred. 


fflush 


fflush 


Format 


Argument 


Description 


Writes out any buffered information for the specified file. 


#include <stdio.h> 
int fflush (FILE *file_ptr); 


file_ptr 
A file pointer. If this argument is a NULL pointer, all buffers associated with all 
currently open files are flushed. 


The output files are normally buffered only if they are not directed to a terminal, 
except for stderr, which is not buffered by default. 


The ff£lush function flushes the HP C RTL buffers. However, RMS has its own 
buffers. The fflush function does not guarantee that the file will be written to 
disk. (See the description of fsync for a way to flush buffers to disk.) 


If the file pointed to by file_ptr was opened in record mode and if there is 
unwritten data in the buffer, then fflush always generates a record. 


Return Values 


0 Indicates that the operation is successful. 


EOF Indicates that the buffered data cannot be 
written to the file, or that the file control block is 
not associated with an output file. 
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ffs 


ffs 

Finds the index of the first bit set in a string. 
Format 

#include <strings.h> 

int ffs (int iteger); 
Argument 

integer 

The integer to be examined for the first bit set. 
Description 


The ffs function finds the first bit set (beginning with the least significant bit) 
and returns the index of that bit. Bits are numbered starting at 1 (the least 
significant bit). 

Return Values 


The index of the first bit set. 
0 If index is 0. 


REF-188 


fgetc 


fgetc 

Returns the next character from a specified file. 
Format 

#include <stdio.h> 

int fgetc (FILE *file_ptr); 
Argument 


file_ptr 
A pointer to the file to be accessed. 
Description 
The fgetc function returns the next character from the specified file. 


Compiling with the __ UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


See also the fgetc_unlocked function and the getc macro. 


Return Values 


x The returned character. 
EOF Indicates the end-of-file or an error. 


REF-189 


fgetc_unlocked (pia, 164) 


fgetc_unlocked (Alpha, 164) 


Format 


Argument 


Description 


Same as the fgetc function, except used only within a scope protected by 
flockfile and funlockfile. 


#include <stdio.h> 
int fgetc_unlocked (FILE *file_ptr); 


file_ptr 
A file pointer. 


The reentrant version of the fgetc function is locked against multiple threads 
calling it simultaneously. This incurs overhead to ensure integrity of the stream. 
The unlocked version of this call, fgetc_unlocked can be used to avoid the 
overhead. The fgetc_unlocked function is functionally identical to the fgetc 
function, except that fgetc_unlocked can be safely used only within a scope that 
is protected by the flockfile and funlockfile functions used as a pair. The 
caller must ensure that the stream is locked before fgetc_unlocked is used. 


Compiling with the __ UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


See also getc_unlocked, flockfile, ftrylockfile, and funlockfile. 


Return Values 
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n The returned character. 
EOF Indicates the end-of-file or an error. 


fgetname 


fgetname 


Format 


Returns the file specification associated with a file pointer. 


#include <stdio.h> 


char *fgetname (FILE “file_ptr, char *buffer, ... ); 


Function Variants 


Arguments 


Description 


The fgetname function has variants named fgetname32 and fgetnameé4 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


file_ptr 
A file pointer. 


buffer 
A pointer to a character string that is large enough to hold the file specification. 


An optional additional argument that can be either 1 or 0. If you specify 1, 
the fgetname function returns the file specification in OpenVMS format. If you 
specify 0, fgetname returns the file specification in UNIX style format. If you 
do not specify this argument, fgetname returns the file name according to your 
current command language interpreter. For more information about UNIX style 
file specifications, see Section 1.4.3. 


The fgetname function places the file specification at the address given in the 
buffer. The buffer should be an array large enough to contain a fully qualified file 
specification (the maximum length is 256 characters). 


Return Values 


Restriction 


The address of the buffer. 


0 Indicates an error. 


The fgetname function is specific to the HP C RTL and is not portable. 
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fgetpos 


fgetpos 


Stores the current file position for a given file. 


Format 


#include <stdio.h> 


int fgetpos (FILE “stream, fpos_t *pos); 


Arguments 


stream 


A file pointer. 


pos 


A pointer to an implementation-defined structure. The fgetpos function fills this 
structure with information that can be used on subsequent calls to fsetpos. 


Description 


The fgetpos function stores the current value of the file position indicator for the 
stream pointed to by stream into the object pointed to by pos. 


Return Values 


0 
-1 


Example 
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Indicates successful completion. 
Indicates that there are errors. 


#include <stdio.h> 
#include <stdlib.h> 


main () 


{ 


FILE *fp; 
int stat, 
1; 
int character; 
char ch, 
c ptr[130], 
d_ptr[130]; 
fpos t posit; 


/* Open a file for writing. */ 


if ((fp = fopen("file.dat", "w+")) == NULL) { 
perror ("open") ; 
exit (1); 


/* Get the beginning position in the file. */ 


if (fgetpos(fp, &posit) != 0) 
perror ("fgetpos") ; 


/* Write some data to the file. */ 


if (fprintf(fp, "this is a test\n") == 0) { 
perror("fprintf") ; 
exit (1); 


fgetpos 


/* Set the file position back to the beginning. */ 


if (fsetpos(fp, &posit) != 0) 
perror("fsetpos") ; 


fgets(c_ptr, 130, fp); 


puts(c_ptr); /* Should be "this is a test." */ 
/* Close the file. */ 
if (fclose(fp) != 0) { 

perror ("close") ; 

exit (1); 
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fgets 


fgets 


Format 


Reads a line from the specified file, up to one less than the specified maximum 
number of characters or up to and including the new-line character, whichever 
comes first. The function stores the string in str. 


#include <stdio.h> 


char “fgets (char “str, int maxchar, FILE *file_ptr); 


Function Variants 


Arguments 


Description 


The fgets function has variants named fgets32 and fgetsé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


str 
A pointer to a character string that is large enough to hold the information 
fetched from the file. 


maxchar 
The maximum number of characters to fetch. 


file_ptr 
A file pointer. 


The fgets function terminates the line with a null character (\0). Unlike gets, 
fgets places the new-line character that terminates the input line into the user 
buffer if more than maxchar characters have not already been fetched. 


When the file pointed to by file_ptr is opened in record mode, fgets treats the 
end of a record the same as a new-line character, so it reads up to and including 
a new-line character or to the end of the record. 


Return Values 


Example 
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x Pointer to str. 


NULL Indicates the end-of-file or an error. The contents 
of str are undefined if a read error occurs. 


#include <stdio.h> 
#include <stdlib.h> 
#include <unixio.h> 


main () 
FILE *fp; 
char c_ptr[130]; 


/* Create a dummy data file */ 


fgets 


if ((fp = fopen("file.dat", "w+")) == NULL) { 
perror ("open") ; 
exit (1); 


fprintf£ (fp, "this is a test\n") ; 


fclose(fp) ; 
/* Open a file with some data -"this is a test" */ 
if ((fp = fopen("file.dat", "r+")) == NULL) { 
perror("open error") ; 
exit (1); 


fgets(c_ptr, 130, fp); 
puts(c_ ptr); /* Display what fgets got. */ 
fclose(fp) ; 


delete ("file.dat") 
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fgetwc 


fgetwc 
Reads the next character from a specified file, and converts it to a wide-character 
code. 
Format 
#include <wchar.h> 
wint_t fgetwc (FILE *file_ptr); 
Argument 


file_ptr 
A pointer to the file to be accessed. 


Description 


Upon successful completion, the fgetwc function returns the wide-character code 
read from the file pointed to by file_ptr and converted to type wint_t. If the file 

is at end-of-file, the end-of-file indicator is set, and WEOF is returned. If an I/O 

read error occurred, then the error indicator is set, and WEOF is returned. 


Applications can use ferror or feof to distinguish between an error condition 
and an end-of-file condition. 


Return Values 


x The wide-character code of the character read. 

WEOF Indicates the end-of-file or an error. If a read 
error occurs, the function sets errno to one of the 
following: 


e EALREADY — An operation is already in 
progress on the same file. 


e EBADF - The file descriptor is not valid. 
e EILSEQ - Invalid character detected. 
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fgetws 


fgetws 


Format 


Reads a line of wide characters from a specified file. 


#include <wchar.h> 


wehar_t “fgetws (wchar_t *wstr, int maxchar, FILE *file_ptr); 


Function Variants 


Arguments 


Description 


The fgetws function has variants named fgetws32 and fgetws64 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


wsir 
A pointer to a wide-character string large enough to hold the information fetched 
from the file. 


maxchar 
The maximum number of wide characters to fetch. 


file_ptr 
A file pointer. 


The fgetws function reads wide characters from the specified file and stores them 
in the array pointed to by wstr. The function reads up to maxchar—1 characters 
or until the new-line character is read, converted, and transferred to wstr, or 
until an end-of-file condition is encountered. The function terminates the line 
with a null wide character. fgetws places the new-line that terminates the input 
line into the user buffer, unless maxchar characters have already been fetched. 


Return Values 


Example 


x Pointer to wstr. 


NULL Indicates the end-of-file or an error. The contents 
of wstr are undefined if a read error occurs. Ifa 
read error occurs, the function sets errno. For a 
list of possible errno values, see fgetwc. 


#include <stdlib.h> 
#include <stdio.h> 
#include <locale.h> 
#include <wchar.h> 


main () 
wchar t wstr[80], 


*ret; 
FILE *fp; 
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fgetws 


/* Create a dummy data file */ 


if ((fp = fopen("file.dat", "w+")) == NULL) { 
perror ("open") ; 
exit (1); 


fprintf(fp, "this is a test\n") ; 
fclose(fp) ; 


/* Open a test file containing : "this is a test" */ 


if ((fp = fopen("file.dat", "r")) == (FILE *) NULL) { 
perror("File open error") ; 
exit (EXIT_FAILURE) ; 


ret = fgetws(wstr, 80, fp); 

if (ret == (wchar_t *) NULL) { 
perror("fgetws failure") ; 
exit (EXIT_FAILURE) ; 


fputws(wstr, stdout) ; 
fclose(fp) ; 
delete ("file.dat") ; 
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fileno 


fileno 
Returns the file descriptor associated with the specified file pointer. 
Format 
#include <stdio.h> 
int fileno (FILE *file_ptr); 
Argument 
file_ptr 
A file pointer. 
Description 


If you are using version 5.2 or lower of the C compiler, undefine the fileno 
macro: 


#if defined (fileno) 
#undef fileno 
#endif 


Return Values 


x Integer file descriptor. 
—1 Indicates an error. 
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finite (ipra, 164) 


finite cipra, 164 


Returns the integer value 1 (TRUE) when its argument is a finite number, or 0 
(FALSE) if not. 


Format 

#include <math.h> 

int finite (double x); 

int finitef (float x); 

int double finitel (long double x); 
Argument 

x 

A real value. 
Description 


The finite functions return 1 when —Infinity < x < +Infinity. They return 0 
when |x| = Infinity, or x is a NaN. 
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flockfile «ina, 164) 


flockfile tipi, 16 


Format 


Argument 


Description 


Locks a stdio stream. 


#include <stdio.h> 
void flockfile (FILE *file_ptr; 


file_ptr 
A file pointer. 


The flockfile function locks a stdio stream so that a thread can have exclusive 
use of that stream for multiple I/O operations. Use the flockfile function for 

a thread that wants to ensure that the output of several printf functions, for 
example, is not garbled by another thread also trying to use printf. 


File pointers passed are assumed to be valid; flockfile will perform locking even 
on invalid file pointers. Also, the funlockfile function will not fail if the calling 
thread does not own a lock on the file pointer passed. 


Matching flockfile and funlockfile calls can be nested. If the stream has been 
locked recursively, it will remain locked until the last matching funlockfile is 
called. 


All C RTL file-pointer I/O functions lock their file pointers as if calling flockfile 
and funlockfile. 


See also ftrylockfile and funlockfile. 
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floor 


floor 

Returns the largest integer less than or equal to the argument. 
Format 

#include <math.h> 

double floor (double x); 

float floorf (float x); (Azpha, 164) 

long double floorl (long double x); (Alpha, 164) 
Argument 


4 
A real value. 


Return Value 


n The largest integer less than or equal to the 
argument. 
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fma (ipha, 164) 


fma (Alpha, I64) 


Computes (x * y) + z, rounded as one ternary operation. 


Format 

#include <math.h> 

double fma (double x, double y, double 2); 

float fmaf (float x, float y, float z); 

long double fmal (long double x, long double y, long double 2); 
Argument 

X,Y,Z 

Real values. 
Description 


The fma functions compute (x * y) + z, rounded as one ternary operation: the 
value is computed as if to infinite precision and rounded once to the result 
format, according to the rounding mode characterized by the value of FLT_ 
ROUNDS. 


Return Values 


n Upon success, (x * y) + z, rounded as one ternary 
operation. 
NaN x or y is NaN; errno is set to EDOM. 
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fmax (ipha, 164 


fmax (Alpha, 164) 


Returns the maximum numeric value of its arguments. 


Format 

#include <math.h> 

double fmax (double x, double y); 

float fmaxf (float x, float y); 

long double fmaxl (long double x, long double y); 
Argument 


x 
A real value. 


A real value. 


Description 


The fmax functions determine the maximum numeric value of their arguments. 
NaN arguments are treated as missing data: if one argument is a NaN and the 
other numeric, then the numeric value is returned. 


Return Values 


n Upon success, the maximum numeric value of 
the arguments. If just one argument is a NaN, 
the other argument is returned. 


NaN Both x and y are NaNs. 
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fMiN (Alpha, 164) 


fmin (Alpha, 164) 


Returns the minimum numeric value of its arguments. 


Format 

#include <math.h> 

double fmin (double x, double y); 

float fminf (float x, float y); 

long double fminl (long double x, long double y); 
Argument 

x 

A real value. 

A real value. 
Description 


The fmin functions determine the minimum numeric value of their arguments. 
NaN arguments are treated as missing data: if one argument is a NaN and the 
other numeric, then the numeric value is returned. 


Return Values 


n Upon success, the minimum numeric value of the 
arguments. If just one argument is a NaN, the 
other argument is returned. 


NaN Both x and y are NaNs. 
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fmod 


fmod 

Computes the floating-point remainder. 
Format 

#include <math.h> 

double fmod (double x, double y); 

float fmodf (float x, float y); (Alpha, 164) 

long double fmod! (long double x, long double y); (Alpha, 164) 
Arguments 

x 

A real value. 

A real value. 
Description 


The fmod functions return the floating-point remainder of the first argument 
divided by the second. If the second argument is 0, the function returns 0. 


Return Values 


x The value f, which has the same sign as the 
argument x, such that x == i « y + f for some 
integer i, where the magnitude of f is less than 
the magnitude of y. 


0 Indicates that y is 0. 
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fopen 


fopen 


Format 


Arguments 


Description 


Opens a file by returning the address of a FILE structure. 


#include <stdio.h> 
FILE *fopen (const char “file_spec, const char *a_mode); (ANSI C) 


FILE *fopen (const char *file_spec, const char *a_mode, ... ); (HP C Extension) 


file_spec 
A character string containing a valid file specification. 


a_mode 

The access mode indicator. Use one of the following character strings: "r", "w", 
"an, "re, "we, "rb", "r+b", "rb+", "wh", "w+b", "wh+", "ab", "a+b", "ab+", or 
" at W iM 


These access modes have the following effects: 
e "r" opens an existing file for reading. 


e "w" creates a new file, if necessary, and opens the file for writing. If the file 
exists, it creates a new file with the same name and a higher version number. 


e a" opens the file for append access. An existing file is positioned at the 
end-of-file, and data is written there. If the file does not exist, the HP C RTL 
creates it. 


The update access modes allow a file to be opened for both reading and writing. 
When used with existing files, "r+" and "a+" differ only in the initial positioning 
within the file. The modes are: 


e "r+" opens an existing file for read update access. It is opened for reading, 
positioned first at the beginning-of-file, but writing is also allowed. 


e "w+" opens a new file for write update access. 


e a+" opens a file for append update access. The file is first positioned at the 
end-of-file (writing). If the file does not exist, the HP C RTL creates it. 


e "b" means binary access mode. In this case, no conversion of carriage-control 
information is attempted. 


Optional file attribute arguments. The file attribute arguments are the same as 
those used in the creat function. For more information, see the creat function. 


If a version of the file exists, a new file created with fopen inherits certain 
attributes from the existing file unless those attributes are specified in the fopen 
call. The following attributes are inherited: 


Record format 
Maximum record size 
Carriage control 


REF-207 


fopen 


File protection 


If you specify a directory in the file name and it is a search list that contains an 
error, HP C for OpenVMS Systems interprets it as a file open error. 


The file control block can be freed with the fclose function, or by default on 
normal program termination. 


Return Values 


x File pointer. 


NULL Indicates an error. The constant NULL is defined 
in the <stdio.h> header file to be the NULL 
pointer value. The function returns NULL to 
signal the following errors: 


e File protection violations 


e Attempts to open a nonexistent file for read 
access 


e Failure to open the specified file 
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fp_class (ipha, 164) 


fp_class dipia, 164 


Determines the class of IEEE floating-point values. 


Format 

#include <math.h> 

int fp_class (double x); 

int fp_classf (float x); 

int fp_class| (long double x); 
Argument 

x 

An IEEE floating-point number. 
Description 


The fp class functions determine the class of the specified IEEE floating- 
point number, returning a constant from the <fp_class.h> header file. They 
never cause an exception, even for signaling NaNs (Not-a-Number). These 
functions implement the recommended class (x) function in the appendix of the 
IEEE 754-1985 standard for binary floating-point arithmetic. The constants in 
<fp_class.h> refer to the following classes of values: 


FP_SNAN 
FP_QNAN 
FP_POS_INF 
FP_NEG_INF 
FP_POS_NORM 
FP_NEG_NORM 
FP_POS_DENORM 
FP_NEG_DENORM 
FP_POS_ZERO 
FP_NEG_ZERO 


Return Value 


Signaling NaN (Not-a-Number) 
Quiet NaN 

+Infinity 

—Infinity 

positive normalized 

negative normalized 

positive denormalized 

negative denormalized 

+0.0 (positive zero) 

—0.0 (negative zero) 


A constant from the <fp_class.h> header file. 
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fpathconf 


fpathconf 


Format 


Arguments 


Description 
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Retrieves file implementation characteristics. 


#include <unistd.h> 


long int fpathconf (int filedes, int name); 


filedes 
An open file descriptor. 


name 
The configuration attribute to query. If this attribute is not applicable to the file 
specified by the filesdes argument, fpathconf returns an error. 


The fpathconf function allows an application to retrieve the characteristics of 
operations supported by the file system underlying the file named by the filesdes 
argument. Read, write, or execute permission of the named file is not required, 
but you must be able to search all directories in the path leading to the file. 


Symbolic values for the name argument are defined in the <unistd.h> header file 
as follows: 


_PC_LINK MAX The maximum number of links to the file. If the filedes 
argument refers to a directory, the value returned 
applies to the directory itself. 

_PC_MAX_CANON The maximum number of bytes in a canonical input line. 
This is applicable only to terminal devices. 


_PC_MAX_INPUT The number of types allowed in an input queue. This is 
applicable only to terminal devices. 
_PC_NAME_MAX Maximum number of bytes in a file name (not including 


a terminating null). The byte range value is between 13 
and 255. This is applicable only to a directory file. The 
value returned applies to filenames within the directory. 


_PC_PATH_MAX Maximum number of bytes in a pathname (not including 
a terminating null). The value is never larger than 
65,535. This is applicable only to a directory file. The 
value returned is the maximum length of a relative 
pathname when the specified directory is the working 
directory. 


_PC_PIPE_BUF Maximum number of bytes guaranteed to be written 
atomically. This is applicable only to a FIFO. The 
value returned applies to the referenced object. If the 
path argument refers to a directory, the value returned 
applies to any FIFO that exists or can be created within 
the directory. 


_PC_CHOWN_ 
RESTRICTED 


_PC_NO_TRUNC 


_PC_VDISABLE 


Return Values 


fpathconf 


The value returned applies to any files (other than 
directories) that exist or can be created within the 
directory. This is applicable only to a directory file. 
Returns 1 if supplying a component name longer than 
allowed by NAME_MAX causes an error. Returns 0 
(zero) if long component names are truncated. This is 
applicable only to a directory file. 

This is always 0 (zero); no disabling character is defined. 
This is applicable only to a terminal device. 


The resultant value for the configuration 
attribute specified in the name argument. 
Indicates an error; errno is set to one of the 
following values: 


e EINVAL — The name argument specifies an 
unknown or inapplicable characteristic. 


e EBADF - the filedes argument is not a valid 
file descriptor. 
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fprintf 


fprintf 


Format 


Arguments 


Example 


Performs formatted output to a specified file. 


#include <stdio.h> 


int fprintf (FILE *file_ptr, const char *format_spec, . .. ); 


file_ptr 
A pointer to the file to which the output is directed. 


format_spec 
A pointer to a character string that contains the format specification. For more 
information on format specifications and conversion characters, see Chapter 2. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, the output sources can be omitted. 
Otherwise, the function calls must have exactly as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Any excess output sources are ignored. 


An example of a conversion specification follows: 


include <stdio.h> 


main () 


int temp = 4, temp2 = 17; 


fprintf(stdout, "The answers are %d, and %d.", temp, temp2); 


This example outputs the following to the stdout file: 


The answers are 4, and 17. 


For a complete description of the format specification and the output source, see 
Chapter 2. 


Return Values 
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x The number of bytes written, excluding the null 
terminator. 


Negative value 


fprintf 


Indicates an error. The function sets errno to 
one of the following: 


EILSEQ — Invalid character detected. 
EINVAL -— Insufficient arguments. 


ENOMEM — Not enough memory available 
for conversion. 


ERANGE -— Floating-point calculations 
overflow. 


EVMSERR — Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This might indicate that 
conversion to a numeric value failed because 
of overflow. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


EBADF — The file descriptor is not valid. 
EIO — I/O error. 


ENOSPC — No free space on the device 
containing the file. 


ENXIO — Device does not exist. 
EPIPE — Broken pipe. 


ESPIPE — Illegal seek in a file opened for 
append. 


EVMSERR — Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 
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fputc 


fputc 

Writes a character to a specified file. 
Format 

#include <stdio.h> 

int fputc (int character, FILE *file_ptr); 
Arguments 

character 

An object of type int. 

file_ptr 

A file pointer. 
Description 


The fputc function writes a single character to the specified file and returns the 
character. 


Compiling with the __UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


See also the fputc_unlocked function and the putc macro. 


Return Values 


x The character written to the file. Indicates 
success. 
EOF Indicates an output error. 
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fputc_unlocked (ipia, 164) 


fputc_unlocked apna, 164) 


Same as the fputc function, except used only within a scope protected by 
flockfile and funlockfile. 


Format 
#include <stdio.h> 
int fputc_unlocked (int character, FILE *file_ptr); 
Arguments 
character 
The character to be written. An object of type int. 
file_ptr 
A file pointer. 
Description 


See the putc_unlocked macro. 


Compiling with the __UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


See also flockfile, ftrylockfile, and funlockfile. 


Return Values 


n The returned character. 
EOF Indicates the end-of-file or an error. 
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fputs 


fputs 
Writes a character string to a file without copying the string’s null terminator 
(\ 0). 
Format 
#include <stdio.h> 
int fouts (const char *sir, FILE *file_ptn); 
Arguments 
str 
A pointer to a character string. 
file_ptr 
A file pointer. 
Description 


Unlike puts, the fputs function does not append a new-line character to the 
output string. 


See also puts. 


Return Values 


Nonnegative value Indicates success. 
EOF Indicates an error. 
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fputwc 


fputwc 
Converts a wide character to its corresponding multibyte value, and writes the 
result to a specified file. 
Format 
#include <wchar.h> 
wint_t foutwc (wint_t we, FILE *file_ptn); 
Arguments 
wc 
An object of type wint_t. 
file_ptr 
A file pointer. 
Description 


The fputwc function writes a wide character to a file and returns the character. 


See also putwe. 


Return Values 


x The character written to the file. Indicates 
success. 
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fputwc 
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WEOF 


Indicates an output error. The function sets 
errno to the following: 


e EILSEQ — Invalid wide-character code 
detected. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


e EBADF - The file descriptor is not valid. 
e EIO—TI/O error. 


e ENOSPC — No free space on the device 
containing the file. 


e ENXIO — Device does not exist. 
e EPIPE - Broken pipe. 


e ESPIPE — Illegal seek in a file opened for 
append. 


e EVMSERR -— Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 


fputws 


fputws 


Format 


Arguments 


Description 


Writes a wide-character string to a file without copying the null-terminating 
character. 


#include <wchar.h> 


int fputws (const wchar_t *wstr, FILE *file_ptr); 


wsir 
A pointer to a wide-character string. 


file_ptr 
A file pointer. 


The fputws function converts the specified wide-character string to a multibyte 
character string and writes it to the specified file. The function does not append 
a terminating null byte corresponding to the null wide-character to the output 
string. 


Return Values 


Nonnegative value Indicates success. 


—1 Indicates an error. The function sets errno. For 
a list of the values, see fputwe. 
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fread 


fread 


Format 


Arguments 


Description 


Reads a specified number of items from the file. 


#include <stdio.h> 


size_t fread (void *ptr, size_t size_of_item, size_t number_items, FILE “file_ptr); 


ptr 

A pointer to the location, within memory, where you place the information being 
read. The type of the object pointed to is determined by the type of the item being 
read. 


size_of_item 
The size of the items being read, in bytes. 


number_items 
The number of items to be read. 


file_ptr 
A pointer that indicates the file from which the items are to be read. 


The type size_t is defined in the header file <stdio.h> as follows: 
typedef unsigned int size t 


The reading begins at the current location in the file. The items read are placed 
in storage beginning at the location given by the first argument. You must also 
specify the size of an item, in bytes. 


If the file pointed to by file_ptr was opened in record mode, fread will read 
size_of_item multiplied by number_items bytes from the file. That is, it does not 
necessarily read number_items records. 


Return Values 
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n The number of bytes read divided by size_of_ 
item. 
0 Indicates the end-of-file or an error. 


free 


free 


Format 


Argument 


Description 


Makes available for reallocation the area allocated by a previous calloc, malloc, 
or realloc call. 


#include <stdlib.h> 
void free (void *ptr); 


ptr 
The address returned by a previous call to malloc, calloc, or realloc. If ptrisa 
NULL pointer, no action occurs. 


The ANSI C standard defines free as not returning a value; therefore, the 
function prototype for free is declared with a return type of void. However, since 
a free can fail, and since previous versions of the HP C RTL have declared free 
to return an int, the implementation of free does return 0 on success and —1 on 
failure. 
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freopen 


freopen 


Format 


Arguments 


Description 


Substitutes the file named by a file specification for the open file addressed by a 
file pointer. The latter file is closed. 


#include <stdio.h> 


FILE *freopen (const char *file_spec, const char “a_mode, FILE *file_ptr, ... ); 


file_spec 

A pointer to a string that contains a valid OpenVMS or UNIX style file 
specification. After the function call, the given file pointer is associated with 
this file. 


a_mode 
The access mode indicator. See the fopen function for a description. 


file_ptr 
A file pointer. 


Optional file attribute arguments. The file attribute arguments are the same as 
those used in the creat function. 


The freopen function is typically used to associate one of the predefined names 
stdin, stdout, or stderr with a file. For more information about these predefined 
names, see Chapter 2. 


Return Values 
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file_ptr The file pointer, if freopen is successful. 
NULL Indicates an error. 


frexp 


frexp 
Calculates the fractional and exponent parts of a floating-point value. 
Format 
#include <math.h> 
double frexp (double value, int *eptr); 
float frexpf (float value, int *eptr); (Alpha, 164) 
long double frexp! (long double value, int *eptr); (Alpha, 164) 
Arguments 
value 
A floating-point number of type double, float, or long double. 
eptr 
A pointer to an int where frexp places the exponent. 
Description 
The frexp functions break the floating-point number (value) into a normalized 
fraction and an integral power of 2, as follows: 
value = fraction * (2€XP) 
The fractional part is returned as the return value. The exponent is placed in the 
integer variable pointed to by eptr. 
Example 


#include <math.h> 


main () 


double val = 16.0, fraction; 
int exp; 


fraction = frexp(val, &exp); 
printf ("fraction = %f\n",fraction) ; 
printf ("exp = %d\n",exp); 


} 


In this example, frexp converts the value 16 to .5 + 2°. The example produces the 
following output: 


fraction = 0.500000 
exp = 5 


| value | = Infinity or NaN is an invalid argument. 
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frexp 


Return Values 
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The fractional part of value. 
Both parts of the result are 0. 


If value is NaN, NaN is returned, errno is set to 
EDOM, and the value of *eptr is unspecified. 

If | value | = Infinity, value is returned, errno 
is set to EDOM, and the value of *eptr is 
unspecified. 


fscanf 


fscanf 


Format 


Arguments 


Description 


Performs formatted input from a specified file, interpreting it according to the 
format specification. 


#include <stdio.h> 


int fscanf (FILE *file_ptr, const char *format_spec, ... ); 


file_ptr 
A pointer to the file that provides input text. 


format_spec 
A pointer to a character string that contains the format specification. For more 
information on conversion characters, see Chapter 2. 


Optional expressions whose results correspond to conversion specifications given 
in the format specification. 


If no conversion specifications are given, you can omit the input pointers. 
Otherwise, the function calls must have exactly as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


An example of a conversion specification follows: 


#include <stdio.h> 


main () 


{ 


int temp, temp2; 
fscanf(stdin, "Sd %d", &temp, &temp2) ; 
printf("The answers are %d, and %d.", temp, temp2) ; 
Consider a file, designated by stdin, with the following contents: 
4 17 
The example conversion specification produces the following result: 
The answers are 4, and 17. 


For a complete description of the format specification and the input pointers, see 
Chapter 2. 
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fscanf 


Return Values 


x The number of successfully matched and 
assigned input items. 
EOF Indicates that the end-of-file was encountered or 


a read error occurred. If a read error occurs, the 
function sets errno to one of the following: 


e EILSEQ - Invalid character detected. 


e EVMSERR — Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This can indicate that conversion 
to a numeric value failed due to overflow. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


e EBADF - The file descriptor is not valid. 
e KEIO -— I/O error. 

e ENXIO — Device does not exist. 

e EPIPE —- Broken pipe. 


e EVMSERR - Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 
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fseek 


fseek 


Format 


Arguments 


Description 


Positions the file to the specified byte offset in the file. 


#include <stdio.h> 


int fseek (FILE *file_ptr, long int offset, int direction); 


file_ptr 
A file pointer. 


offset 
The offset, specified in bytes. 


direction 

An integer indicating the position to which the offset is added to calculate the 
new position. The new position is the beginning of the file if direction is SEEK_ 
SET, the current value of the file position indicator if direction is SEEK_CUR, or 
end-of-file if direction is SEEK_END. 


The fseek function can position a fixed-length record-access file with no carriage 
control or a stream-access file on any byte offset, but can position all other files 
only on record boundaries. 


The available Standard I/O functions position a variable-length or VFC record 
file at its first byte, at the end-of-file, or on a record boundary. Therefore, the 
arguments given to fseek must specify any of the following: 


e The beginning or end of the file 
e A 0 offset from the current position (an arbitrary record boundary) 

e The position returned by a previous, valid ftell call 

See the fgetpos and fsetpos functions for a portable way to seek to arbitrary 
locations with these types of record files. 
CAUTION 


If, while accessing a stream file, you seek beyond the end-of-file and then 
write to the file, the fseek function creates a hole by filling the skipped 
bytes with zeros. 


In general, for record files, fseek should only be directed to an absolute 
position that was returned by a previous valid call to ftell, or to the 
beginning or end of a file. If a call to fseek does not satisfy these 
conditions, the results are unpredictable. 


See also open, creat, dup, dup2, and lseek. 
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fseek 


Return Values 


0 Indicates successful seeks. 
—1 Indicates improper seeks. 
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fseeko 


fseeko 


Format 


Arguments 


Description 


Positions the file to the specified byte offset in the file. Equivalent to fseek. 


#include <stdio.h> 


int fseeko (FILE *file_ptr, off_t offset, int direction): 


file_ptr 
A file pointer. 


offset 

The offset, specified in bytes. The off t data type is either a 32-bit or 64-bit 
integer. The 64-bit interface allows for file sizes greater than 2 GB, and can 
be selected at compile time by defining the LLARGEFILE feature-test macro as 
follows: 


CC/DEFINE= LARGEFILE 


direction 

An integer indicating the position to which the offset is added to calculate the 
new position. The new position is the beginning of the file if direction is SEEK_ 
SET, the current value of the file position indicator if direction is SEEK_CUR, or 
end-of-file if direction is SEEK_END. 


The fseeko function is identical to the fseek function, except that the offset 
argument is of type off_t instead of long int. 
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fsetpos 


fsetpos 
Sets the file position indicator for a given file. 
Format 
#include <stdio.h> 
int fsetpos (FILE “stream, const fpos_t *pos); 
Arguments 
stream 
A file pointer. 
pos 
A pointer to an implementation-defined structure. The fgetpos function fills this 
structure with information that can be used on subsequent calls to fsetpos. 
Description 


Call the fgetpos function before using the fsetpos function. 
Return Values 


0 Indicates success. 
—1 Indicates an error. 
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fstat 


fstat 


Format 


Accesses information about the file specified by the file descriptor. 


#include <stat.h> 


int fstat (int file_desc, struct stat *buffer); 


Function Variants 


Arguments 


Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the fstat function that 
is equivalent to the behavior before OpenVMS Version 7.0. 


file_desc 
A file descriptor. 


buffer 

A pointer to a structure of type stat_t, which is defined in the <stat.h> header 
file. The argument receives information about that particular file. The members 
of the structure pointed to by buffer are: 


Member Type Definition 

st_dev dev_t Pointer to a physical device name 
st_ino[3] ino _t Three words to receive the file ID 
st_mode mode _t File “mode?” (prot, dir, ... ) 

st_nlink nlink t For UNIX system compatibility only 
st_uid uid _t Owner user ID 

st_gid gid t Group member: from st_uid 

st_rdev dev_t UNIX system compatibility — always 0 
st_size OfE Et File size, in bytes. For st_size to 


report a correct value, you need to 
flush both the C RTL and RMS buffers. 


st_atime time _t File access time; always the same as 
st_mtime 

st_mtime time _t Last modification time 

st_ctime time t File creation time 

st_fab_rfm char Record format 

st_fab_rat char Record attributes 

st_fab_fsz char Fixed header size 

st_fab_mrs unsigned Record size 


The types dev_t, ino t, off _t, mode t, nlink t, uid_t, gid_t, and time t, are 
defined in the <stat.h> header file. However, when compiling for compatibility 
(//DEFINE=_DECC_V4_SOURCE), only dev_t, ino t, and off_t are defined. 
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fstat 


The off t data type is either a 32-bit or 64-bit integer. The 64-bit interface 
allows for file sizes greater than 2 GB, and can be selected at compile time by 
defining the LARGEFILE feature-test macro as follows: 


CC/DEFINE= LARGEFILE 


As of OpenVMS Version 7.0, times are given in seconds since the Epoch (00:00:00 
GMT, January 1, 1970). 


The st_mode structure member is the status information mode and is defined in 
the <stat.h> header file. The st_mode bits follow: 


Bits Constant Definition 

0170000 S_IFMT Type of file 

0040000 S_IFDIR Directory 

0020000 S_IFCHR Character special 

0060000 S_IFBLK Block special 

0100000 S_IFREG Regular 

0030000 S_IFMPC Multiplexed char special 
0070000 S_IFMPB Multiplexed block special 
0004000 S_ISUID Set user ID on execution 
0002000 S_ISGID Set group ID on execution 
0001000 S_ISVTX Save swapped text even after use 
0000400 S_IREAD Read permission, owner 

0000200 S_IWRITE Write permission, owner 

0000100 S_IEXEC Execute/search permission, owner 


Description 
The fstat function does not work on remote network files. 


Be aware that for the stat_t structure member st_size to report a correct value, 
you need to flush both the C RTL and RMS buffers. 


Note (Alpha, 164) 


On OpenVMS Alpha and I64 systems, the stat, fstat, utime, and utimes 
functions have been enhanced to take advantage of the new file-system 
support for POSIX compliant file timestamps. 


This support is available only on ODS-5 devices on OpenVMS Alpha and 
164 systems beginning with a version of OpenVMS Alpha after Version 
7.3. 


Before this change, the stat and fstat functions were setting the values 
of the st_ctime, st_mtime, and st_atime fields based on the following file 
attributes: 


st_ctime - ATR$C_CREDATE (file creation time) 
st_mtime - ATR$C_REVDATE (file revision time) 
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Return Values 


fstat 


st_atime - was always set to st_mtime because no support for file 
access time was available 


Also, for the file-modification time, utime and utimes were modifying 
the ATR$C_REVDATE file attribute, and ignoring the file-access-time 
argument. 


After the change, for a file on an ODS-5 device, the stat and fstat 
functions set the values of the st_ctime, st_mtime, and st_atime fields 
based on the following new file attributes: 


st_ctime - ATR$C_ATTDATE (last attribute modification time) 
st_mtime - ATR$C_MODDATE (last data modification time) 
st_atime - ATR$C_ACCDATE (last access time) 


If ATR$C_ACCDATE is zero, as on an ODS-2 device, the stat and fstat 
functions set st_atime to st_mtime. 


For the file-modification time, the utime and utimes functions modify 
both the ATR$C_REVDATE and ATR$C_MODDATE file attributes. For 
the file-access time, these functions modify the ATR$C_ACCDATE file 
attribute. Setting the ATR$C_MODDATE and ATR$C_ACCDATE file 
attributes on an ODS-2 device has no effect. 

For compatibility, the old behavior of stat, fstat, utime, and utimes 
remains the default, regardless of the kind of device. 

The new behavior must be explicitly enabled at run time by defining 
the DECC$EFS_FILE_TIMESTAMPS logical name to "ENABLE" before 
invoking the application. Setting this logical does not affect the behavior 
of stat, fstat, utime and utimes for files on an ODS-2 device. 


Indicates successful completion. 


Indicates an error other than a protection 
violation. 


Indicates a protection violation. 
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fstatvfs (ipne, 164 


fstatvf$ cipia, 164 


Format 


Arguments 


Description 
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Gets information about a device containing the specified file. 


#include <statvfs.h> 


int fstatvfs (int filedes, struct statvfs “buffer); 


filedes 
File descriptor obtained from a successful open or fcnt1 function call. 


buffer 
Pointer to a statvfs structure to hold the returned information. 


The fstatvfs function returns descriptive information about the device 
containing the specified file. Read, write, or execute permission of the specified 
file is not required. The returned information is in the format of a statvfs 
structure, which is defined in the <statvfs.h> header file and contains the 
following members: 


unsigned long f_bsize - Preferred block size. 

unsigned long f_frsize - Fundamental block size. 

fsblkcnt_t £ blocks - Total number of blocks in units of f_frsize. 
fsblkcnt_t f_bfree - Total number of free blocks. If £ bfree would assume 
a meaningless value due to the misreporting of free block count by $GETDVI 


for a DFS disk, then f_bfree is set to the maximum block count. 


fsblkcnt_t f_bavail - Number of free blocks available. Set to the unused 
portion of the caller’s disk quota. 


fsfilcnt_t £ files - Total file (inode) count. 


fsfilcnt_t f_ffree - Free file (inode) count. For OpenVMS systems, this 
value is calculated as freeblocks/clustersize. 


fsfilcnt_t f favail - Free file (inode) count nonprivileged. Set to f_ffree. 


unsigned long f_fsid - File system identifier. This identifier is based on the 
allocation-class device name. This gives a unique value based on device, as 
long as the device is locally mounted. 


unsigned long f_flag - Bit mask representing one or more of the following 
flags: 


ST_RONLY - The volume is read-only. 
ST _NOSUID - The volume has protected subsystems enabled. 


fstatvfs (aipna, 164) 


unsigned long f namemax - Maximum length of a file name. 
char f basetype[64] - Device-type name. 

char f_fstr[64] - Logical volume name. 

char __ reserved[64] - Media type name. 


Upon successful completion, fstatvfs returns 0 (zero). Otherwise, it returns —1 
and sets errno to indicate the error. 


See also statvfs. 
Return Value 


0 Sucessful completion. 
—1 Indicates an error. errno is set to one of the 
following: 


e EBADF - The file descriptor parameter 
contains an invalid value. 


e KIO - An I/O error occurred while reading 
the device. 


e EINTR - A signal was caught during 
execution of the function. 


e EOVERFLOW - One of the values to be 
returned cannot be represented correctly in 
the structure pointed to by buffer. 
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fsync 


fsync 

Flushes data all the way to the disk. 
Format 

#include <unistd.h> 

int fsync (int fd); 
Argument 


fd 
A file descriptor corresponding to an open file. 
Description 


The fsync function behaves much like the fflush function. The primary 
difference between the two is that fsync flushes data all the way to the disk 
while fflush flushes data only as far as the underlying RMS buffers. Also, with 
fflush, you can flush all buffers at once; with fsync you cannot. 


Return Values 


0 Indicates successful completion. 
—1 Indicates an error. 
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ftell 


ftell 


Format 


Argument 


Description 


Returns the current byte offset to the specified stream file. 


#include <stdio.h> 
long int ftell (FILE *file_ptr); 


file_ptr 
A file pointer. 


The ftell function measures the byte offset from the beginning of the file. 


For variable-length files, VFC files, or any file with carriage-control attributes, if 
the file is opened in record mode, then ftell returns the starting position of the 
current record, not the current byte offset. 


When using record files, the ftell function ignores any characters that have 
been pushed back using either ungetc or ungetwc. This behavior does not occur if 
stream files are being used. 


For a portable way to measure the exact offset for any type of file, see the fgetpos 
function. 


Return Values 


n The current offset. 
EOF Indicates an error. 
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ftello 


ftello 


Format 


Argument 


Description 
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Returns the current byte offset to the specified stream file. This function is 
equivalent to ftell. 


#include <stdio.h> 
off_t ftello (FILE *file_ptr); 


file_ptr 
A file pointer. 


The ftello function is identical to the ftell function, except that the return 
value is of type off_t instead of long int. 


The off t data type is either a 64-bit or 32-bit integer. The 64-bit interface 
allows for file sizes greater than 2 GB, and can be selected at compile time by 
defining the LARGEFILE feature-test macro as follows: 


CC/DEFINE= LARGEFILE 


ftime 


ftime 


Format 


Returns the elapsed time since 00:00:00, January 1, 1970, in the structure pointed 
at by timeptr. 


#include <timeb.h> 


int ftime (struct timeb *timeptr); 


Function Variants 


Argument 


Description 


Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the ftime function that 
is equivalent to the behavior before OpenVMS Version 7.0. 


timeptr 
A pointer to the structure timeb t. 


The typedef timeb t refers to the following structure defined in the <timeb.h> 
header file: 


typedef struct timeb 


time_t time; 

unsigned short millitm; 
short timezone; 
short dstflag; 


B 
The member time gives the time in seconds. 
The member millitm gives the fractional time in milliseconds. 


After a call to ftime, the timezone and dstflag members of the timeb structure 
have the values of the global variables timezone and dstflag, respectively. See 
the description of the tzset function for timezone and dstflag global variables. 


Return Values 


0 Successful execution. The timeb t structure is 
filled in. 


—1 Indicates an error. Failure might indicate that 
the system’s time-differential factor (that is, the 
difference between the system time and UTC 
time) is not set correctly. 

If the value of the SYS$TIMEZONE_ 
DIFFERENTIAL logical is wrong, the function 
fails with errno set to EINVAL. 
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ftruncate 


ftruncate 


Format 


Arguments 


Description 


Truncates a file to a specified length. 


#include <unistd.h> 


int ftruncate (int filedes, off_t length); 


filedes 
The descriptor of a file that must be open for writing. 


length 

The new length of the file, in bytes. The off _t data type is either a 32-bit or 
64-bit integer. The 64-bit interface allows for file sizes greater than 2 GB, and 
can be selected at compile time by defining the LARGEFILE feature-test macro 
as follows: 


CC/DEFINE= LARGEFILE 


The ftruncate function truncates a file at the specified position. For record files, 
the position must be a record boundary. Also, the files must be local, regular files. 


If the file was previously larger than Jength, extra data is lost. If the file was 
previously shorter than length, bytes between the old and new lengths are read 
as Zeros. 


Return Values 
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0 Indicates success. 


—1 An error occurred; errno is set to indicate the 
error. 


ftrylockfile (aipna, 64 


ftrylockfile (Alpha, 164) 


Acquires ownership of a stdio (FILE*) object. 


Format 

#include <stdio.h> 

int ftrylockfile (FILE *file_ptr); 
Argument 

file_ptr 

A file pointer. 
Description 


The ftrylockfile function is used by a thread to acquire ownership of a 
stdio (FILE*) object, if the object is available. The ftrylockfile function is a 
non-blocking version of flockfile. 


The ftrylockfile function returns zero for success and nonzero to indicate that 
the lock cannot be acquired. 


See also flockfile and funlockfile. 


Return Values 


0 Indicates success. 
nonzero Indicates the lock cannot be acquired. 
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ftw 


ftw 


Format 


Arguments 


Description 
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Walks a file tree. 


#include <ftw.h> 


int ftw (const char *path, int(*function)(const char *, const struct stat *, int), int depth); 


path 
The directory hierarchy to be searched. 


function 
The function to be invoked for each file in the directory hierarchy. 


depth 
The maximum number of directory streams or file descriptors, or both, available 
for use by ftw. This argument should be in the range of 1 to OPEN_MAX. 


The ftw function recursively searches the directory hierarchy that descends from 
the directory specified by the path argument. 


For each file in the hierarchy, ftw calls the function specified by the function 
argument, passes it a pointer to a null-terminated character string containing the 
name of the file, a pointer to a stat structure containing information about the 
file, and an integer. 


The integer identifies the file type. Possible values, defined in <ftw.h> are: 


FTW_F Regular file. 

FTW_D Directory. 

FTW_DNR Directory that cannot be read. 

FTW_NS A file on which stat could not successfully be executed. 


If the integer is FTW_DNR, then the files and subdirectories contained in that 
directory are not processed. 


If the integer is FTW_NS, then the stat structure contents are meaningless. For 
example, a file in a directory for which you have read permission but not execute 
(search) permission can cause the function argument to pass FTW_NS. 


The ftw function finishes processing a directory before processing any of its files 
or subdirectories. 


The ftw function continues the search until: 
e The directory hierarchy specified by the path argument is completed. 


e An invocation of the function specified by the function argument returns a 
nonzero value. 


e An error (such as an J/O error) is detected within the ftw function. 


Because the ftw function is recursive, it is possible for it to terminate with a 
memory fault because of stack overflow when applied to very deep file structures. 


ftw 


The ftw function uses the malloc function to allocate dynamic storage during 
its operation. If ftw is forcibly terminated, as with a call to longjmp from the 
function pointed to by the function argument, ftw has no chance to free that 
storage. It remains allocated. 


A safe way to handle interrupts is to store the fact that an interrupt has occurred, 
and arrange to have the function specified by the function argument return a 
nonzero value the next time it is called. 


Notes 


The ftw function is reentrant; make sure that the function supplied 
as argument function is also reentrant. 


The C RTL supports a standard-compliant definition of the stat 
structure and associated definitions. To use them, compile your 
application with the UUSE_STD_STAT feature-test macro defined. See 
the <stat.h> header file on your system for more information. 


See also malloc, longjump, and stat. 


Return Values 


Indicates success. 


Indicates that the function specified by the 
function argument stops its search, and returns 
the value that was returned by the function. 


Indicates an error; errno is set to one of the 
following values: 


EACCHES -— Search permission is denied for 
any component of the path argument or read 
permission is denied for the path argument. 


ENAMETOOLONG - The length of the path 
string exceeds PATH MAX, or a pathname 
component is longer than NAME_MAX while 
[_POSIX_NO_TRUNC] is in effect. 


ENOENT -— The path argument points to the 
name of a file that does not exist or points to 
an empty string. 


ENOMEM - There is insufficient memory for 
this operation. 


Also, if the function pointed to by the function 
argument encounters an error, errno can be set 
accordingly. 
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funlockfile cipia, 164 


funlockfile (Alpha, 164) 


Format 


Argument 


Description 
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Unlocks a stdio stream. 


#include <stdio.h> 
void funlockfile (FILE *file_ptr); 


file_ptr 
A file pointer. 


The funlockfile function unlocks a stdio stream, causing the thread that had 
been holding the lock to relinquish exclusive use of the stream. 


File pointers passed are assumed to be valid; flockfile will perform locking even 
on invalid file pointers. Also, the funlockfile function will not fail if the calling 
thread does not own a lock on the file pointer passed. 


Matching flockfile and funlockfile calls can be nested. If the stream has been 
locked recursively, it will remain locked until the last matching funlockfile is 
called. 


All C RTL file-pointer I/O functions lock their file pointers as if calling flockfile 
and funlockfile. 


See also flockfile and ftrylockfile. 


fwait 


fwait 

Waits for I/O on a specific file to complete. 
Format 

#include <stdio.h> 

int fwait (FILE *fp); 
Argument 


fp 
A file pointer corresponding to an open file. 


Description 


The fwait function is used primarily to wait for completion of pending 
asynchronous I/O. 


Return Values 


0 Indicates successful completion. 
—1 Indicates an error. 
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fwide 


fwide 


Format 


Arguments 


Description 


Determines and sets the orientation of a stream. 


#include <wchar.h> 


int fwide (FILE “stream, int mode); 


stream 
A file pointer. 


mode 
A value that specifies the desired orientation of the stream. 


The fwide function determines the orientation of the stream pointed to by stream 
and sets the orientation of a nonoriented stream according to the mode argument 
in the following way: 


If the mode argument is: Then the fwide function: 

greater than zero makes the stream wide-oriented. 

less than zero makes the stream byte-oriented. 

zero does not alter the orientation of the stream. 


If the orientation of the stream has already been set, fwide does not alter it. 
Because no error status is defined for fwide, the calling application should check 
errno if fwide returns a 0. 


Return Values 


REF-246 


>0 After the call, the stream is wide-oriented. 

<0 After the call, the stream is byte-oriented. 

0 After the call, the stream has no orientation or 
a stream argument is invalid; the function sets 
errno. 


fwprintf 


fwprintf 


Format 


Arguments 


Description 


Writes output to the stream under control of the wide-character format string. 


#include <wchar.h> 


int fwprintf (FILE “stream, const wchar_t *format,... ): 


stream 
A file pointer. 


format 

A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, the output sources can be omitted. 
Otherwise, the function calls must have exactly as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Any excess output sources are ignored. 


The fwprintf function writes output to the stream pointed to by stream under 
control of the wide-character string pointed to by format, which specifies how 

to convert subsequent arguments to output. If there are insufficient arguments 
for the format, the behavior is undefined. If the format is exhausted while 
arguments remain, the excess arguments are evaluated, but are otherwise 
ignored. The fwprintf function returns when it encounters the end of the format 
string. 


The format argument is composed of zero or more directives that include: 
e Ordinary wide characters (not the percent sign (% )) 


e Conversion specifications 


Return Values 


n The number of wide characters written. 
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fwprintf 


Negative value Indicates an error. The function sets errno to 
one of the following: 


e EILSEQ - Invalid character detected. 
e EINVAL - Insufficient arguments. 


e ENOMEM — Not enough memory available 
for conversion. 


e ERANGE - Floating-point calculations 
overflow. 


e EVMSERR - Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This might indicate that 
conversion to a numeric value failed because 
of overflow. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


e EBADF - The file descriptor is not valid. 
e EIO—TI/O error. 


e ENOSPC — No free space on the device 
containing the file. 


e ENXIO — Device does not exist. 
e EPIPE - Broken pipe. 


e ESPIPE — Illegal seek in a file opened for 
append. 


e EVMSERR -— Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 


Example 


The following example shows how to print a date and time in the form "Sunday, 
July 3, 10:02", followed by z to five decimal places: 


include <math.h> 

include <stdio.h> 

include <wchar.h> 

/* oo. */ 

wchar_t *weekday, *month; /* pointers to wide-character strings */ 
int day, hours, min; 

fwprintf (stdout, L"%ls, %ls %d, %.2d:%.2d\n", 

weekday, month, day, hour, min); 

fwprintf (stdout, L"pi = %.5f£\n", 4 * atan(1.0)); 
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fwrite 


fwrite 


Format 


Arguments 


Description 


Writes a specified number of items to the file. 


#include <stdio.h> 


size_t fwrite (const void *ptr, size_t size_of_item, size_t number_items, FILE *file_ptr); 


ptr 
A pointer to the memory location from which information is being written. The 
type of the object pointed to is determined by the type of the item being written. 


size_of_item 
The size, in bytes, of the items being written. 


number_items 
The number of items to be written. 


file_ptr 
A file pointer that indicates the file to which the items are being written. 


The type size_t is defined in the header file <stdio.h> as follows: 
typedef unsigned int size t 


The writing begins at the current location in the file. The items are written from 
storage beginning at the location given by the first argument. You must also 
specify the size of an item, in bytes. 


If the file pointed to by file_ptr is a record file, the fwrite function outputs at 
least number_items records, each of length size_of_item. 


Return Value 


x The number of items written. The number of 
records written depends upon the maximum 
record size of the file. 
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fwscanf 


fwscanf 


Format 


Arguments 


Description 
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Reads input from the stream under control of the wide-character format string. 


#include <wchar.h> 


int fwscanf (FILE *stream, const wchar_t *format, ... ); 


stream 
A file pointer. 


format 

A pointer to a wide-character string containing the format specification. For more 
information about format and conversion specifications and their corresponding 
arguments, see Chapter 2. 


Optional expressions whose results correspond to conversion specifications given 
in the format specification. For more information about format and conversion 
specifications and their corresponding arguments, see Chapter 2. 


If no conversion specifications are given, you can omit the input pointers. 
Otherwise, the function calls must have exactly as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


The fwscanf function reads input from the stream pointed to by stream under the 
control of the wide-character string pointed to by format. If there are insufficient 
arguments for the format, the behavior is undefined. If the format is exhausted 
while arguments remain, the excess arguments are evaluated, but otherwise 
ignored. 


The format is composed of zero or more directives that include: 
e One or more white-space wide characters. 


e An ordinary wide character (neither a percent (% )) nor a white-space wide 
character). 


e Conversion specifications. 
Each conversion specification is introduced by the wide character %. 


If the stream pointed to by the stream argument has no orientation, fwscanf 
makes the stream wide-oriented. 


Return Values 


n 


EOF 


fwscanf 


The number of input items assigned, sometimes 
fewer than provided for, or even zero, in the 
event of an early matching failure. 

Indicates an error; input failure occurs before 
any conversion. 
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gcvt 


gcevt 


Format 


Converts its argument to a null-terminated string of ASCII digits and returns the 
address of the string. 


#include <stdlib.h> 


char *gcvt (double value, int ndigit, char *buffer); 


Function Variants 


Arguments 


Description 
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The gcvt function has variants named gcvt32 and gcvté4 for use with 32-bit 
and 64-bit pointer sizes, respectively. See Section 1.10 for more information on 
using pointer-size-specific functions. 


value 

An object of type double that is converted to a null-terminated string of ASCII 
digits. 

ndigit 

The number of ASCII digits to use in the converted string. If ndigit is less than 
6, the value of 6 is used. 


buffer 
A storage location to hold the converted string. 


The gcvt function places the converted string in a buffer and returns the address 
of the buffer. If possible, gcvt produces ndigit significant digits in F-format, or if 
not possible, in E-format. Trailing zeros are suppressed. 


The ecvt, fcvt, and gcvt functions represent the following special values 
specified in the IEEE Standard for floating-point arithmetic: 


Value Representation 
Quiet NaN NaNQ 
Signalling NaN NaNS 
+Infinity Infinity 
—Infinity —Infinity 


The sign associated with each of these values is stored into the sign argument. In 
IEEE floating-point representation, a value of 0 (zero) can be positive or negative, 
as set by the sign argument. 


See also fcvt and ecvt. 


gcevt 


Return Value 


x The address of the buffer. 
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getc 


getc 


Format 


Argument 


Description 


Returns the next character from a specified file. 


#include <stdio.h> 
int getc (FILE *file_ptr); 


file_ptr 
A pointer to the file to be accessed. 


The getc macro returns the next byte from the input stream specified by the 
file_ptr parameter and moves the file pointer, if defined, ahead one byte in the 
input stream. 


Since getc is a macro, a file pointer argument with side effects (for example, 
getc (*f£++)) might be evaluated incorrectly. In such a case, use the fgetc 
function instead. See the fgetc function. 


See also getc_unlocked. 


Return Values 
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n The returned character. 
EOF Indicates the end-of-file or an error. 


getc_unlocked (pha, 164) 


getc_unlocked apie, 14 


Same as getc, except used only within a scope protected by flockfile and 


funlockfile. 
Format 

#include <stdio.h> 

int getc_unlocked (FILE *file_ptr); 
Argument 

file_ptr 

A file pointer. 
Description 


The reentrant version of the getc macro is locked against multiple threads calling 
it simultaneously. This incurs overhead to ensure integrity of the stream. The 
unlocked version of this call, getc_unlocked can be used to avoid the overhead. 
The getc_unlocked macro is functionally identical to the getc macro, except that 
it is not required to be implemented in a thread-safe manner. The getc_unlocked 
macro can be safely used only within a scope that is protected by the flockfile 
and funlockfile functions used as a pair. The caller must ensure that the 
stream is locked before getc_unlocked is used. 


Since getc_unlocked is a macro, a file pointer argument with side effects might 
be evaluated incorrectly. In such a case, use the fgetc_unlocked function instead. 


See also flockfile, ftrylockfile, and funlockfile. 


Return Values 


n The returned character. 
EOF Indicates the end-of-file or an error. 
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[w]getch 


[w]getch 
Get a character from the terminal screen and echo it on the specified window. 
The getch function echoes the character on the stdscr window. 
Format 
#include <curses.h> 
char getch( ); 
char wgetch (WINDOW “*win); 
Argument 


win 
A pointer to the window. 


Description 


The getch and wgetch functions refresh the specified window before fetching a 
character. For more information, see the scrollok function. 


Return Values 


x The returned character. 


ERR Indicates that the function makes the screen 
scroll illegally. 
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getchar 


getchar 

Reads a single character from the standard input (stdin). 
Format 

#include <stdio.h> 

int getchar (void); 
Description 


The getchar function is identical to fgetc(stdin). 


See also getchar_ unlocked. 
Return Values 


x The next character from stdin, converted to int. 
EOF Indicates the end-of-file or an error. 
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getchar_unlocked (ipia, 16 


getchar_unlocked apie, 164 


Format 


Description 


Same as getchar, except used only within a scope protected by flockfile and 
funlockfile. 


#include <stdio.h> 


int getchar_unlocked (void); 


The reentrant version of the getchar function is locked against multiple threads 
calling it simultaneously. This incurs overhead to ensure integrity of the input 
stream. The unlocked version of this call, getchar_unlocked can be used to avoid 
the overhead. The getchar_unlocked function is functionally identical to the 
getchar function, except that it is not required to be implemented in a thread- 
safe manner. The getchar_unlocked function can be safely used only within a 
scope that is protected by the flockfile and funlockfile functions used as a 
pair. The caller must ensure that the stream is locked before getchar_unlocked 
is used. 


See also flockfile, ftrylockfile, and funlockfile. 


Return Values 
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x The next character from stdin, converted to int. 
EOF Indicates the end-of-file or an error. 


getclock 


getclock 


Format 


Arguments 


Description 


Gets the current value of the systemwide clock. 


#include <timers.h> 


int getclock (int clktyp, struct timespec *tp); 


clktyp 
The type of systemwide clock. 


tp 
Pointer to a timespec structure space where the current value of the systemwide 
clock is stored. 


The getclock function sets the current value of the clock specified by clktyp into 
the location pointed to by tp. 


The clktyp argument is given as a symbolic constant name, as defined in the 
<timers.h> header file. Only the TIMEOFDAY symbolic constant, which specifies 
the normal time-of-day clock to access for systemwide time, is supported. 


For the clock specified by TIMEOFDAY, the value returned by this function is 
the elapsed time since the Epoch. The Epoch is referenced to 00:00:00 UTC 
(Coordinated Universal Time) 1 Jan 1970. 


The getclock function returns a timespec structure, which is defined in the 
<timers.h> header file as follows: 
struct timespec { 


unsigned long tv_sec /* Elapsed time in seconds since the Epoch*/ 
long tv_nsec /* Elapsed time as a fraction of a second */ 
/* since the Epoch (in nanoseconds) */ 


bi 


Return Values 


0 Indicates success. 
—1 Indicates an error; errno is set to one of the 
following values: 
e EINVAL -— The clkiyp argument does not 
specify a known systemwide clock. 


Or, the value of SYS$TIMEZONE_ 
DIFFERENTIAL logical is wrong. 


e IO — An error occurred when the 
systemwide clock specified by the clktyp 
argument was accessed. 
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getcwd 


getcwd 


Format 


Returns a pointer to the file specification for the current working directory. 


#include <unistd.h> 
char *getcwd (char “buffer, size_t size); (SO POSIX-1) 


char *getcwd (char “buffer, unsigned int size, ... ); (HP C Extension) 


Function Variants 


Arguments 


The getcwd function has variants named getcwd32 and getcwd64 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


buffer 
Pointer to a character string large enough to hold the directory specification. 


If buffer is a NULL pointer, getcwd obtains size bytes of space using malloc. 
In this case, you can use the pointer returned by getcwd as the argument in a 
subsequent call to free. 


size 
The length of the directory specification to be returned. 


An optional argument that can be either 1 or 0. If you specify 1, the directory 
specification is returned in OpenVMS format. If you specify 0, the directory 
specification (pathname) is returned in UNIX style format. If you omit this 
argument, getcwd returns the file name according to your current command- 
language interpreter (CLI). For more information about UNIX style directory 
specifications, see Section 1.4.3. 


Return Values 
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x A pointer to the file specification. 
NULL Indicates an error. 


getdtablesize 


getdtablesize 


Gets the total number of file descriptors that a process can have open 
simultaneously. 

Format 
#include <unistd.h> 


int getdtablesize (void); 


Description 


The getdtablesize function returns the total number of file descriptors that a 
process can have open simultaneously. Each process is limited to a fixed number 
of open file descriptors. 


The number of file descriptors that a process can have open is the minumum of 
the following: 


e HPC RTL open file limit—65535 on OpenVMS Alpha and 164; 2048 on 
OpenVMS VAX. 


e SYSGEN CHANNELCNT parameter—permanent I/O channel count. 
e Process open file quota FILLM parameter—number of open files that can be 
opened by a process at one time. 


Return Values 


x The number of file descriptors that a process can 
have open simultaneously. 


—1 Indicates an error. 
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getegid 


getegid 


Format 


Description 


With POSIX IDs disabled, this function is equivalent to getgid and returns the 
group number from the user identification code (UIC). 


With POSIX IDs enabled, this function returns the effective group ID of the 
calling process. 


#include <unistd.h> 


gid_t getegid (void); 


The getegid function can be used with POSIX style identifiers (IDs) or with 
UIC-based identifiers. 


POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher. 


With POSIX style IDs disabled, the getegid and getgid functions are equivalent 
and return the group number from the current UIC. For example, if the UIC is 
[313,031], 313 is the group number. 


With POSIX style IDs enabled, getegid returns the effective group ID of the 
calling process, and getgid returns the real group ID of the calling process. The 
real group ID is specified at login time. The effective group ID is more transient, 
and determines additional access permission during execution of a set-group-ID 
process. It is for such processes that the getgid function is most useful. 


The getegid function is always successful; no return value is reserved to indicate 
an error. 


To enable/disable POSIX style IDs, see Section 1.7. 


See also geteuid and getuid. 


Return Value 
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x The effective group ID (POSIX IDs enabled), or 
the group number from the UIC (POSIX IDs 
disabled). 


getenv 


getenv 


Format 


Argument 


Description 


Searches the environment array for the current process and returns the value 
associated with a specified environment name. 


#include <stdlib.h> 


char “*getenv (const char *name); 


name 
One of the following values: 


HOME —Your login directory 

TERM—tThe type of terminal being used 

PATH—The default device and directory 

USER—The name of the user who initiated the process 

Logical name or command-language interpreter (CLI) symbolic name 


An environment variable set with setenv or putenv 


The case of the specified name is important. 


In certain situations, the getenv function attempts to perform a logical name 
translation on the user-specified argument: 


1. 


If the argument to getenv does not match any of the environment strings 
present in your environment array, getenv attempts to translate your 
argument as a logical name by searching the logical name tables indicated by 
the LNM$FILE_DEV logical, as is done for file processing. 


getenv first does a case-sensitive lookup. If that fails, it does a case- 
insensitive lookup. In most instances, logical names are defined in uppercase, 
but getenv can also find logical names that include lowercase letters. 


getenv does not perform iterative logical name translation. 


If the logical name is a search list with multiple equivalence values, the 
returned value points to the first equivalence value. For example: 


$ DEFINE A B,C 
ptr = getenv("A"); 
A returns a pointer to "B". 


If no logical name exists, getenv attempts to translate the argument string as 
a CLI symbol. If it succeeds, it returns the translated symbol text. If it fails, 
the return value is NULL. 


getenv does not perform iterative CLI translation. 
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getenv 


If your CLI is the DEC/Shell, the function does not attempt a logical name 
translation since Shell environment symbols are implemented as DCL symbols. 


Notes 


e In OpenVMS Version 7.1, a cache of OpenVMS environment variables 
(that is, logical names and DCL symbols) was added to the getenv 
function to avoid the library making repeated calls to translate a 
logical name or to obtain the value of a DCL symbol. By default, 
the cache is disabled. If your application does not need to track 
changes in OpenVMS environment variables that can occur during its 
execution, the cache can be enabled by enabling the DECC$ENABLE_ 
GETENV_CACHE logical before invoking the application. 


e Do not use the setenv, getenv, and putenv functions to manipulate 
symbols and logicals. Instead use the OpenVMS library calls 
libSset_ logical, lib$get logical, lib$set symbol, and 
lib$get_ symbol. The *env functions deliberately provide UNIX 
behavior, and are not a substitute for these OpenVMS runtime library 
calls. 


OpenVMS DCL symbols, not logical names, are the closest analog 

to environment variables on UNIX systems. While getenv is a 
mechanism to retrieve either a logical name or a symbol, it maintains 
an internal cache of values for use with setenv and subsequent 
getenv calls. The setenv function does not write or create DCL 
symbols or OpenVMS logical names. 


This is consistent with UNIX behavior. On UNIX systems, setenv 
does not change or create any symbols that will be visible in the shell 
after the program exits. 


Return Values 


x Pointer to an array containing the translated 
symbol. An equivalence name is returned at 
index zero. 

NULL Indicates that the translation failed. 
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geteuid 


geteuid 


Format 


Description 


With POSIX IDs disabled, this function is equivalent to getuid and returns the 
member number (in OpenVMS terms) from the user identification code (UIC). 


With POSIX IDs enabled, this function returns the effective user ID. 


#include <unistd.h> 


uid_t geteuid (void); 


The geteuid function can be used with POSIX style identifiers (IDs) or with 
UIC-based identifiers. 


POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher. 


With POSIX style IDs disabled (the default), the geteuid and getuid functions 
are equivalent and return the member number from the current UIC as follows: 


e For programs compiled with the VMS _V6_SOURCE feature-test macro or 
programs that do not include the <unistd.h> header file, the getuid and 
geteuid functions return the member number of the OpenVMS UIC. For 
example, if the UIC is [313,31], then the member number, 31, is returned. 


e For programs compiled without the VMS _V6_SOURCE feature-test macro 
that do include the <unistd.h> header file, the full UIC is returned. For 
example, if the UIC is [313, 31] then 20512799 (31 + 313 * 65536) is returned. 


With POSIX style IDs enabled, geteuid returns the effective user ID of the 
calling process, and getuid returns the real user ID of the calling process. 


To enable/disable POSIX style IDs, see Section 1.7. 
See also getegid and getgid. 


Return Value 


x The effective user ID (POSIX IDs enabled), or 
the member number from the current UIC or the 
full UIC (POSIX IDs disabled). 
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getgid 


getgid 


Format 


Description 


With POSIX IDs disabled, this function is equivalent to getegid and returns the 
group number from the user identification code (UIC). 


With POSIX IDs enabled, this function returns the real group ID. 


#include <unistd.h> 


gid_t getgid (void); 


The getgid function can be used with POSIX style identifiers or with UIC-based 
identifiers. 


POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher. 


With POSIX style IDs disabled (the default), the getegid and getgid functions 
are equivalent and return the group number from the current UIC. For example, 
if the UIC is [313,031], 313 is the group number. 


With POSIX style IDs enabled, getegid returns the effective group ID of the 
calling process, and getgid returns the real group ID of the calling process. The 
real group ID is specified at login time. The effective group ID is more transient, 
and determines additional access permission during execution of a set-group-ID 
process. It is for such processes that the getgid function is most useful. 


To enable/disable POSIX style IDs, see Section 1.7. 


See also geteuid and getuid. 


Return Value 
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x The real group ID (POSIX IDs enabled), or the 
group number from the current UIC (POSIX IDs 
disabled). 


getgrent ipna, 164) 


getgrent apr, 16 


Format 


Description 


Gets a group database entry. 


#include <grp.h> 


struct group *getgrent (void); 


The getgrent function returns the next group in the sequential search, returning 
a pointer to a structure containing the broken-out fields of an entry in the group 
database. 


When first called, getgrent returns a pointer to a group structure containing 
the first entry in the group database. Thereafter, it returns a pointer to the next 
group structure in the group database, so successive calls can be used to search 
the entire database. 


If an end-of-file or an error is encountered on reading, getgrent returns a NULL 
pointer and sets errno. 


Return Values 


x Pointer to a group structure, if successful. 
NULL Indicates that an error occurred. The function 
sets errno to one of the following values: 


e EACCES — The user process does not have 
appropriate privileges enabled to access the 
user authorization file. 


e EINTR - A signal was caught during the 
operation. 


e EIO — Indicates that an I/O error occurred. 


e EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


e ENFILE — The maximum allowable number 
of files is currently open in the system. 
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getgrgid pra, 164) 


getgrgid aipna, 164 


Gets a group database entry for a group ID. 


Format 

#include <types.h> 

#include <grp.h> 

struct group *getgrgid (gid_t gid); 
Argument 

gid 

The group ID of the group for which the group database entry is to be retrieved. 
Description 


The getgrgid function searches the group database for an entry with a matching 
gid and returns a pointer to the group structure containing the matching entry. 


Return Values 


x Pointer to a valid group structure containing a 
matching entry. 
NULL An error occurred. 


Note: The return value points to a static 
area that is overwritten by subsequent calls 
to getgrent, getgrgid, or getgrnam. 

On error, the function sets errno to one of the 
following values: 


e EACCES — The user process does not have 
appropriate privileges enabled to access the 
user authorization file. 


e EIO-— An J/O error has occurred. 


e EINTR - A signal was caught during 
getgrgid. 

e EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


e ENFILE — The maximum allowable number 
of files is currently open in the system. 


Applications wishing to check for error situations 
should set errno to 0 before calling getgrgid. If 
errno is set on return, an error occurred. 
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getgrgid_r (aipha, 164 


getgrgid_f aipia, 161 


Format 


Arguments 


Description 


Gets a group database entry for a group ID. 


#include <types.h> 
#include <grp.h> 


int getgrgid_r (gid_t gid, struct group *grp, char “buffer, size_t bufsize, struct group **result); 


gid 
The group ID of the group for which the group database entry is to be retrieved. 


grp 
Storage area to hold the retrieved group structure. 


buffer 
The working buffer that is able to hold the longest group entry in the database. 


bufsize 
The length, in characters, of buffer. 


result 
Upon successful return, result points to the retrieved group structure. 


Upon unsuccessful return, result is set to NULL. 


The getgrgid_r function updates the group structure pointed to by grp and 
stores a pointer to that structure at the location pointed to by result. The 
structure contains an entry from the group database with a matching gid. 
Storage referenced by the group structure is allocated from the memory provided 
with the buffer argument, which is bufsize characters in size. The maximum size 
needed for this buffer can be determined with the SC_GETGR_R_SIZE_MAX 
parameter of the sysconf function. On error or if the requested entry is not 
found, a NULL pointer is returned at the location pointed to by result. 
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getgrgid_F (aipha, 164 


Return Values 
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Successful completion. 


On error, the function sets the return value to 
one of the following: 


EACCES — The user process does not have 
appropriate privileges enabled to access the 
user authorization file. 


EIO — An I/O error has occurred. 

EINTR — A signal was caught during 
getgrgid. 

EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


ENFILE — The maximum allowable number 
of files is currently open in the system. 


ERANGE - Insufficient storage was supplied 
through the buffer and bufsize arguments 

to contain the data to be referenced by the 
resulting group structure. 


getgrnam mpna, 164) 


getgrnamM apa, 164 


Gets a group database entry for a name. 


Format 


#include <types.h> 


#include <grp.h> 


struct group *getgrnam (const char *name): 


Argument 


name 


The group name of the group for which the group database entry is to be 


retrieved. 


Description 


The getgrnam function searches the group database for an entry with a matching 
name, and returns a pointer to the group structure containing the matching 


entry. 


Return Values 


NULL 


Pointer to a valid group structure containing a 
matching entry. 

Indicates an error. 

Note: The return value points to a static area 
which is overwritten by subsequent calls to 
getgrent, getgrgid, or getgrnam. 

On error, the function sets the return value to 
one of the following: 


e EACCES — The user process does not have 
appropriate privileges enabled to access the 
user authorization file. 


e EIO-— An J/O error has occurred. 


e EINTR — A signal was caught during 
getgrnam. 


e EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


e ENFILE — The maximum allowable number 
of files is currently open in the system. 


Applications wishing to check for error situations 
should set errno to 0 before calling getgrnam. If 
errno is set on return, an error occurred. 
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getgrnam_F (ipa, 164) 


getgrnam_ 


Format 


Arguments 


Description 
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I (Alpha, 164) 


Gets a group database entry for a name. 


#include <types.h> 
#include <grp.h> 


int getgrnam_r (const char *name, struct group *grp, char “buffer, size_t bufsize, struct group **resullt); 


name 
The group name of the group for which the group database entry is to be 
retrieved. 


grp 
Storage area to hold the retrieved group structure. 


buffer 
The working buffer that is able to hold the longest group entry in the database. 


bufsize 
The length, in characters, of buffer. 


result 
Upon successful return, result points to the retrieved group structure. 


Upon unsuccessful return, result is set to NULL. 


The getgrnam_r function updates the group structure pointed to by grp and 
stores a pointer to that structure at the location pointed to by result. The 
structure contains an entry from the group database with a matching name. 
Storage referenced by the group structure is allocated from the memory provided 
with the buffer argument, which is bufsize characters in size. The maximum size 
needed for this buffer can be determined with the SC_GETGR_R_SIZE_MAX 
parameter of the sysconf function. On error or if the requested entry is not 
found, a NULL pointer is returned at the location pointed to by result. 


Return Values 


getgrnam_F ipha, 164) 


Successful completion. 


On error, the function sets the return value to 
one of the following: 


EACCES — The user process does not have 
appropriate privileges enabled to access the 
user authorization file. 


EIO — An J/O error has occurred. 


EINTR — A signal was caught during 
getgrnam. 


EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


ENFILE — The maximum allowable number 
of files is currently open in the system. 


ERANGE -— Insufficient storage was supplied 
through the buffer and bufsize arguments 

to contain the data to be referenced by the 
resulting group structure. 
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getgroups 


getg roups 
Gets the current supplementary group IDs of the calling process. 


Format 
#include <unistd.h> 


int getgroups (int gidsetsize, gid_t grouplisf ]); 


Arguments 


gidsetsize 
Indicates the number of entries that can be stored in the array pointed to by the 
grouplist parameter. 


grouplist 

Points to the array in which the supplementary group IDs of the process are 
stored. The effective group ID of the process is not returned by the getgroups 
function if it is not also a supplementary group ID of the calling process. 


Description 


The getgroups function gets the current supplementary group IDs of the calling 
process. The list is stored in the array pointed to by the grouplist parameter. The 
gidsetsize parameter indicates the number of entries that can be stored in this 
array. 


The getgroups function never returns more IDs than the value indicated by the 
sysconf parameter SC_NGROUPS_MAX. 


See also getgid and setsid. 


Return Value 


n The number of elements stored in the array 
pointed to by the grouplist parameter. 

—1 Indicates failure. errno might be set to one of 
the following values: 


e EFAULT -— The gidsetsize and grouplist 
parameters specify an array that is partially 
or completely outside of the allocated address 
space of the process. 


e EINVAL — The gidsetsize parameter is 
nonzero and smaller than the number of 
supplementary group IDs. 
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getitimer 


getitimer 


Format 


Arguments 


Description 


Returns the value of interval timers. 


#include <time.h> 


int getitimer (int which, struct itimerval *value); 


which 
The type of interval timer. The HP C RTL supports only ITIMER_REAL. 


value 
Pointer to an itimerval structure whose members specify a timer interval and 
the time left to the end of the interval. 


The getitimer function returns the current value for the timer specified by the 
which argument in the structure pointed to by value. 


A timer value is defined by the itimerval structure: 


struct itimerval { 
struct timeval it_interval; 
struct timeval it_value; 


le 


The following table lists the values for the itimerval structure members: 


itimerval Member Value Meaning 

it_interval = 0 Disables a timer after its next expiration and 
assumes it_value is nonzero. 

it_interval = nonzero Specifies a value used in reloading it value 
when the timer expires. 

it_value = 0 Disables a timer. 

it_value = nonzero Indicates the time to the next timer expiration. 


Time values smaller than the resolution of the system clock are rounded up to 
this resolution. 


The HP C RTL provides each process with one interval timer, defined in the 
<time.h> header file as ITIMER_REAL. This timer decrements in real time and 
delivers a SIGALRM signal when the timer expires. 
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getitimer 


Return Values 


0 Indicates success. 


—1 Indicates an error; errno is set to EINVAL (The 
value argument specified a time that was too 
large to handle.) 
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getlogin 


getlogin 


Format 


Description 


Gets the login name. 


#include <unistd.h> 
char *getlogin (void); 


int *getlogin_r (char *name, size_t namesize); 


The getlogin function returns the login name of the user associated with the 
current session. If getlogin returns a non-null pointer, then that pointer points 
to the name that the user logged in under, even if there are several login names 
with the same user ID. 


The getlogin_r function is the reentrant version of getlogin. Upon successful 
completion, getlogin_r returns 0 and puts the name associated by the login 
activity with the controlling terminal of the current process in the character 
array pointed to by name. The array is namesize characters long and should have 
space for the name and the terminating null character. The maximum size of the 
login name is LOGIN_NAME_MAX. 


If getlogin_r is successful, name points to the name the user used at login, even 
if there are several login names with the same user ID. 


Return Values 


x Upon successful completion, getlogin returns 
a pointer to a null-terminated string in a static 
buffer. 

0 Indicates successful completion of getlogin_r. 

NULL Indicates an error; errno is set. 
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getname 


getname 


Format 


Returns the file specification associated with a file descriptor. 


#include <unixio.h> 


char *getname (int file_desc, char “buffer, . . . ); 


Function Variants 


Arguments 


Description 


The getname function has variants named getname32 and getnameé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


file_desc 
A file descriptor. 


buffer 
A pointer to a character string that is large enough to hold the file specification. 


An optional argument that can be either 1 or 0. If you specify 1, the getname 
function returns the file specification in OpenVMS format. If you specify 0, the 
getname function returns the file specification in UNIX style format. If you omit 
this argument, the getname function returns the file name according to your 
current command-language interpreter (CLI). For more information about UNIX 
style file specifications, see Section 1.4.3. 


The getname function places the file specification into the area pointed to by 
buffer and returns that address. The area pointed to by buffer should be an array 
large enough to contain a fully qualified file specification (the maximum length is 
256 characters). 


Return Values 
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The address passed in the buffer argument. 
0 Indicates an error. 


getopt 


getopt 


Format 


Arguments 


Description 


A command-line parser that can be used by applications that follow UNIX 
command-line conventions. 


#include <unistd.h> (x/Open, POSIX-1) 

#include <stdio.h> (X/Open, POSIX-2) 

int getopt (int argc, char * const argv], const char *optstring); 
extern char “optarg; 


extern int optind, opterr, optopt; 


argc 
The argument count as passed to main. 


argv 
The argument array as passed to main. 


optstring 
A string of recognized option characters. If a character is followed by a colon, the 
option takes an argument. 


The variable optind is the index of the next element of the argu vector to be 
processed. It is initialized to 1 by the system, and it is updated by getopt when 
it finishes with each element of argu. When an element of argu contains multiple 
option characters, it is unspecified how getopt determines which options have 
already been processed. 


The getopt function returns the next option character (if one is found) from 
argu that matches a character in optstring, if there is one that matches. If 
the option takes an argument, getopt sets the variable optarg to point to the 
option-argument as follows: 


e Ifthe option was the last character in the string pointed to by an element 
of argv, then optarg contains the next element of argu, and optind is 
incremented by 2. If the resulting value of optind is not less than argc, 
getopt returns an error, indicating a missing option-argument. 


e Otherwise, optarg points to the string following the option character in that 
element of argu, and optind is incremented by 1. 


If one of the following is true, getopt returns —1 without changing optind: 


argvloptind] is a NULL pointer 
*argu[optind] is not the character — 
argvloptind] points to the string "—" 


If arguloptind] points to the string "— —" getopt returns —1 after incrementing 
optind. 
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getopt 


If getopt encounters an option character not contained in optstring, the question- 
mark character (?) is returned. 


If getopt detects a missing argument, the colon character (:) is returned if the 
first character of optstring is a colon; otherwise, a question-mark character is 
returned. 


In either of the previous two cases, getopt sets the variable optopt to the option 
character that caused the error. If the application has not set the variable opterr 
to 0 and the first character of optstring is not a colon, getopt also prints a 
diagnostic message to stderr. 


Return Values 


Example 


#include 


<u 


x The next option character specified on the 
command line. 
A colon is returned if getopt detects a missing 
argument and the first character of optstring is a 
colon. 
A question mark is returned if getopt encounters 
an option character not in optstring or detects 
a missing argument and the first character of 
optstring is not a colon. 


—1 When all command-line options are parsed. 


The following example shows how you might process the arguments for a utility 
that can take the mutually exclusive options a and b and the options f and o, both 
of which require arguments: 


nistd.h> 


int main (int argc, char *argv[ ]) 
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in 
in 


CC; 


t bflg, aflg, errflg; 


char *ifile; 
char *ofile; 


ex 
ex 


tern char *optarg; 
tern int optind, optopt; 


while ((c = getopt(arge, argv, ":abf:o:)) != -1) { 
switch (c) { 
case ‘a’; 
if (bflg) 
errflgt++; 
else 
aflg++; 
break; 
case 'b': 
if (aflg) 
errflgt++; 
else { 
bflgt++; 
bproc(); 


getopt 


break; 

case 'f': 
ifile = optarg; 
break; 

case ‘Oo’: 
ofile = optarg; 
break; 

case ':': /* -£ or -o without operand */ 
fprintf (stderr, 

"Option -%c requires an operand\n"’ optopt); 

errflgt++; 
break; 

case '?': 
fprintf (stderr, 

"Unrecognized option -%c\n"’ optopt); 

errflgt++; 

} 

if (errflg) { 
fprintf (stderr, "usage: ..."); 
exit (2); 
for ( ; optind < argc; optind++) { 


if (access(argv[optind], R_OK)) { 


This sample code accepts any of the following as equivalent: 


cmd -ao arg path path 

cmd -a -o arg path path 
cmd -o arg -a path path 
cmd -a -o arg -- path path 
cmd -a -oarg path path 

cmd -aoarg path path 
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getpagesize 


getpagesize 
Gets the system page size. 


Format 
#include <unistd.h> 


int getpagesize (void); 


Description 


The getpagesize function returns the number of bytes in a page. The system 
page size is useful for specifying arguments to memory management system calls. 


The page size is a system page size and is not necessarily the same as the 
underlying hardware page size. 


Return Value 


x Always indicates success. Returns the number of 
bytes in a page. 
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getpgid aipra, 164) 


getpgid apna, 164 
Gets the process group ID for a process. 


Format 
#include <unistd.h> 


pid_t getpgid (pid_t pid); 


Argument 
pid 
The process ID for which the group ID is being requested. 


Description 


The getpgid function returns the process group ID of the process specified by 
pid. If pid is 0, the getpgid function returns the process group ID of the calling 
process. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 


x The process group ID of the session leader of the 
specified process. 

(pid_t)—1 Indicates an error. The function sets errno to 
one of the following values: 


e EPERM - The process specified by pid is not 
in the same session as the calling process, 
and the implementation does not allow access 
to the process group ID of that process from 
the calling process. 


e ESRCH - There is no process with a process 
ID of pid. 


e EINVAL — The value of pid is invalid. 
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getpgrp alpha, 164) 


getpgrp aipre, 164) 


Gets the process group ID of the calling process. 


Format 
#include <unistd.h> 


pid_t getpgrp (void); 


Description 
The getpgrp function returns the process group ID of the calling process. 


The getpgrp function is always successful, and no return value is reserved to 
indicate an error. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 


x The process group ID of the calling process. 
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getpid 


getpid 
Returns the process ID of the current process. 


Format 
#include <unistd.h> 


pid_t getpid (void); 
Return Value 


x The process ID of the current process. 
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getppid 


getppid 
Returns the parent process ID of the calling process. 


Format 
#include <unistd.h> 


pid_t getppid (void); 
Return Values 


The parent process ID. 


0 Indicates that the calling process does not have a 
parent process. 
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getpwent 


getpwent 


Format 


Accesses user entry information in the user database, returning a pointer to a 
passwd structure. 


#include <pwd.h> 


struct passwd *getpwent (void); 


Function Variants 


Description 


The getpwent function has variants named _32_getpwent and _64_getpwent 
for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for 
more information on using pointer-size-specific functions. 


The getpwent function returns a pointer to a structure containing fields whose 
values are derived from an entry in the user database. Entries in the database 
are accessed sequentially by getpwent. When first called, getpwent returns a 
pointer to a passwd structure containing the first entry in the user database. 
Thereafter, it returns a pointer to a passwd structure containing the next entry 
in the user database. Successive calls can be used to search the entire user 
database. 


The passwd structure is defined in the <pwd.h> header file as follows: 


pw_name The name of the user. 

pw_uid The ID of the user. 

pw_gid The group ID of the principle group of the user. 
pw_dir The home directory of the user. 

pw_shell The initial program for the user. 


If an end-of-file or an error is encountered on reading, getpwent returns a NULL 
pointer. 


Because getpwent accesses the user authorization file (SYSUAF) directly, the 
process must have appropriate privileges enabled or the function will fail. 


Notes 


All information generated by the getpwent function is stored in a per- 
thread static area and is overwritten on subsequent calls to the function. 


Password file entries that are too long are ignored. 
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getpwent 


Return Values 
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NULL 


Pointer to a passwd structure, if successful. 


Indicates an end-of-file or error occurred. The 
function sets errno to one of the following values: 


e KEIO — Indicates that an I/O error occurred or 
the user does not have appropriate privileges 
enabled to access the user authorization file 
(SYSUAF). 


e EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


e ENFILE — The maximum allowable number 
of files is currently open in the system. 


getpwnam, getpwnam_r 


getpwnam, getpwnam_r 


Format 


The getpwnam function returns information about a user database entry for the 
specified name. 


The getpwnam_r function is a reentrant version of getpwnam. 


#include <pwd.h> 
struct passwd *getpwnam (const char *name); (iSO POSIX-1) 
struct passwd *getpwnam (const char *name, ... ); (HP C Extension) 


int getpwnam_r (const char *name, struct passwd *pwa, char “buffer, size_t bufsize, struct passwd 
**result); (SO POSIX-1), (Alpha, 164) 


int getpwnam_r (const char *name, struct passwd *pwa, char “buffer, size_t bufsize, struct passwd 
“result, ...); (HP C Extension), (Alpha, 164) 


Function Variants 


Arguments 


The getpwnam and getpwnam_r functions have variants named __32_ get pwnam, 
_getpwnam r32 and _ _64 getpwnam, getpwnam r64 for use with 32-bit and 
64-bit pointer sizes, respectively. See Section 1.10 for more information on using 
pointer-size-specific functions. 


name 
The name of the user for which the attributes are to be read. 


pwd 
The address of a passwd structure into which the function writes its results. 


buffer 

A working buffer for the result argument that is able to hold the largest entry 
in the passwd structure. Storage referenced by the passwd structure is allocated 
from the memory provided with the buffer argument, which is bufsize characters 
in length. 


bufsize 
The length of the character array that bujfer points to. 


result 


Upon successful return, is set to pwd. Upon unsuccessful return, the result is set 
to NULL. 


An optional argument that can be either 1 or 0. If you specify 1, the directory 
specification is returned in OpenVMS format. If you specify 0, the directory 
specification (pathname) is returned in UNIX style format. If you omit this 
argument, the function returns the directory specification according to your 
current command-language interpreter. For more information about UNIX style 
directory specifications, see Section 1.4.3. 


REF-289 


getpwnam, getpwnam_r 


Description 


The getpwnam function searches the user database for an entry with the specified 
name. The function returns the first user entry in the database with the pw_name 
member of the passwd structure that matches the name argument. 


The passwd structure is defined in the <pwd.h> header file as follows: 


pw_name The user’s login name. 

pw_uid The numerical user ID. 

pw_gid The numerical group ID. 

pw_dir The home directory of the user. 

pw_shell The initial program for the user. 
Note 


All information generated by the getpwnam function is stored in a per- 
thread static area and is overwritten on subsequent calls to the function. 


The getpwnam_r function is the reentrant version of getpwnam. The getpwnam_r 
function updates the passwd structure pointed to by pwd and stores a pointer 

to that structure at the location pointed to by result. The structure will contain 
an entry from the user database that matches the specified name. Storage 
referenced by the structure is allocated from the memory provided with the bujfer 
argument, which is bufsize characters in length. The maximum size needed for 
this buffer can be determined with the SC_GETPW_R_SIZE_MAX parameter of 
the sysconf function. On error or if the requested entry is not found, a NULL 
pointer is returned at the location pointed to by result. 


Applications wishing to check for error situations should set errno to 0 before 
calling getpwnam. If getpwnam returns a NULL pointer and errno is nonzero, an 
error occurred. 


Return Values 
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x getpwnam returns a pointer to a valid passwd 
structure, if a matching entry is found. 

NULL getpwnam returns NULL if an error occurred or 
a the specified entry was not found. errno is set 


to indicate the error. The getpwnam function may 
fail if: 


e EIO-— An J/O error has occurred. 


e EINTR - A signal was caught during 
getpwnam. 


e EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


e ENFILE — The maximum allowable number 
of files is currently open in the system. 


getpwnam, getpwnam_r 


When successful, getpwnam_r returns 0 and 
stores a pointer to the updated passwd structure 
at the location pointed to by result. 

When unsuccessful (on error or if the requested 
entry is not found), getpwnam_r returns 0 and 
stores a NULL pointer at the location pointed to 
by result. The getpwnam_r function may fail if: 


e ERANGE -— Insufficient storage was supplied 
through buffer and bufsize to contain the 
data to be referenced by the resulting passwd 
structure. 
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getpwuid, getpwuid_f (ipra, 164) 


getpwuid, getpwuid_F dipia, 162 


Format 


The getpwuid function returns information about a user database entry for the 
specified wid. 


The getpwuid r function is a reentrant version of getpwuid. 


#include <pwd.h> 
struct passwd *getpwuid (uid_t uid); @so POSIX-1) 
struct passwd *getpwuid (uid_t uid, ... ); (HP C Extension) 


int getpwuid_r (uid_t uid, struct passwd *pwd, char “buffer, size_t bufsize, struct passwd **result); iso 
POSIX-1) 


int getpwuid_r (uid_t uid, struct passwd “pwd, char “buffer, size_t bufsize, struct passwd **result, . . . ); 
(HP C Extension) 


Function Variants 


Arguments 
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The getpwuid and getpwuid_r functions have variants named _32_ get pwuid, 
_getpwuid_ r32 and _64 getpwuid, getpwuid_ré4 for use with 32-bit and 64- 
bit pointer sizes, respectively. See Section 1.10 for more information on using 
pointer-size-specific functions. 


uid 
The user ID (UID) for which the attributes are to be read. 


pwd 
The location where the retrieved passwd structure is to be placed. 


buffer 

A working buffer for the result argument that is able to hold the entry in the 
passwd structure. Storage referenced by the passwd structure is allocated from 
the memory provided with the buffer argument, which is bufsize characters in 
size. 


bufsize 
The length of the character array that buffer points to. 


result 


Upon successful return, result is set to pwd. Upon unsuccessful return, result is 
set to NULL. 


An optional argument that can be either 1 or 0. If you specify 1, the directory 
specification is returned in OpenVMS format. If you specify 0, the directory 
specification (pathname) is returned in UNIX style format. If you omit this 
argument, the function returns the directory specification according to your 
current command-language interpreter. For more information about UNIX style 
directory specifications, see Section 1.4.3. 


Description 


getpwuid, getpwuid_r aipra, 164) 


The getpwuid function searches the user database for an entry with the specified 
uid. The function returns the first user entry in the database with a pw_uid 
member of the passwd structure that matches the uid argument. 


The passwd structure is defined in the <pwd.h> header file as follows: 


pw_name The user’s login name. 

pw_uid The numerical user ID. 

pw_gid The numerical group ID. 

pw_dir The home directory of the user. 

pw_shell The initial program for the user. 
Note 


All information generated by the getpwuid function is stored in a per- 
thread static area and is overwritten on subsequent calls to the function. 


The getpwuid_r function is the reentrant version of getpwuid. The getpwuid_r 
function updates the passwd structure pointed to by pwd and stores a pointer 

to that structure at the location pointed to by result. The structure will contain 
an entry from the user database with a matching wid. Storage referenced by 
the structure is allocated from the memory provided with the buffer argument, 
which is bufsize characters in size. The maximum size needed for this buffer can 
be determined with the SC_GETPW_R_SIZE_MAX parameter of the sysconf 
function. On error or if the requested entry is not found, a NULL pointer is 
returned at the location pointed to by result. 


Applications wishing to check for error situations should set errno to 0 before 
calling getpwuid. If getpwuid returns a NULL pointer and errno is nonzero, an 
error occurred. 


Return Values 


x getpwuid returns a pointer to a valid passwd 
structure, if a matching entry is found. 


NULL getpwuid returns NULL if an error occurred or 
a matching entry was not found. errno is set to 
indicate the error. The getpwuid function may 
fail if: 


e EIO-— An J/O error has occurred. 


e EINTR — A signal was caught during 
getpwnam. 


e EMFILE — OPEN_MAX file descriptors are 
currently open in the calling process. 


e ENFILE — The maximum allowable number 
of files is currently open in the system. 
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When successful, getpwuid_r returns 0 and 
stores a pointer to the updated passwd structure 
at the location pointed to by result. 


When unsuccessful (on error or if the requested 
entry is not found), getpwuid_r returns 0 and 
stores a NULL pointer at the location pointed to 
by result. The getpwuid_r function may fail if: 


e ERANGE -— Insufficient storage was supplied 
through buffer and bufsize to contain the 
data to be referenced by the resulting passwd 
structure. 


gets 


gets 


Reads a line from the standard input (stdin). 


Format 
#include <stdio.h> 


char “gets (char *str): 


Function Variants 


The gets function has variants named gets32 and _getsé4 for use with 32-bit 
and 64-bit pointer sizes, respectively. See Section 1.10 for more information on 
using pointer-size-specific functions. 


Argument 
str 
A pointer to a character string that is large enough to hold the information 
fetched from stdin. 

Description 


The new-line character (\n) that ends the line is replaced by the function with 
an ASCII null character (\0). 


When stdin is opened in record mode, gets treats the end of a record the same 
as a new-line character and, therefore, reads up to and including a new-line 
character or to the end of the record. 


Return Values 


x A pointer to the str argument. 


NULL Indicates that an error has occurred or that the 
end-of-file was encountered before a new-line 
character was encountered. The contents of str 
are undefined if a read error occurs. 
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getsid ina, 164) 


getsid arpa, 164 


Format 


Argument 


Description 


Gets the process group ID of the session leader. 


#include <unistd.h> 
pid_t getsid (pid_t pid); 


pid 
The process ID of the process whose session leader process group ID is being 
requested. 


The getsid function obtains the process group ID of the process that is the 
session leader of the process specified by pid. If pid is (pid_t)0, it specifies the 
calling process. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 
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x The process group ID of the session leader of the 
specified process. 


(pid_t)—1 Indicates an error. The function sets errno to 
one of the following values: 


e EPERM — The process specified by pid is not 
in the same session as the calling process, 
and the implementation does not allow access 
to the process group ID of the session leader 
of that process from the calling process. 


e ESRCH — There is no process with a process 
ID of pid. 


[w]getstr 


[w]getstr 


Format 


Arguments 


Description 


Get a string from the terminal screen, store it in the variable str, and echo it on 
the specified window. The getstr function works on the stdscr window. 


#include <curses.h> 
int getstr (char “str; 
int wgetstr (WINDOW *win, char *str); 


win 
A pointer to the window. 


str 
Must be large enough to hold the character string fetched from the window. 


The getstr and wgetstr functions refresh the specified window before fetching 
a string. The new-line terminator is stripped from the fetched string. For more 
information, see the scrollok function. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally. 
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gettimeofday 


Format 


Arguments 


Description 


Gets the date and time. 


#include <time.h> 


int gettimeofday (struct timeval “tp, void *tzp); 


tp 
Pointer to a timeval structure, defined in the <time.h> header file. 


tzp 
A NULL pointer. If this argument is not a NULL pointer, it is ignored. 


The gettimeofday function gets the current time (expressed as seconds and 
microseconds) since 00::00 Coordinated Universal Time, January 1, 1970. The 
current time is stored in the timeval structure pointed to by the tp argument. 


The ¢zp argument is intended to hold time-zone information set by the kernel. 
However, because the OpenVMS kernel does not set time-zone information, the 
tzp argument should be NULL. If it is not NULL, it is ignored. This function is 
supported for compatibility with BSD programs. 


If the value of the SYS$STIMEZONE_DIFFERENTIAL logical is wrong, the 
function fails with errno set to EINVAL. 


Return Values 
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0 Indicates success. 


—1 An error occurred. errno is set to indicate the 
error. 


getuid 


getuid 


Format 


Description 


With POSIX IDs disabled, this function is equivalent to geteuid and returns the 
member number (in OpenVMS terms) from the user identification code (UIC). 


With POSIX IDs enabled, returns the real user ID. 


#include <unistd.h> 
uid_t getuid (void); 


The getuid function can be used with POSIX style identifiers or with UIC-based 
identifiers. 


POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher. 


With POSIX style IDs disabled (the default), the geteuid and getuid functions 
are equivalent and return the member number from the current UIC as follows: 


e For programs compiled with the VMS _V6_SOURCE feature-test macro or 
programs that do not include the <unistd.h> header file, the getuid and 
geteuid functions return the member number of the OpenVMS UIC. For 
example, if the UIC is [313,31], then the member number, 31, is returned. 


e For programs compiled without the VMS _V6_SOURCE feature-test macro 
that do include the <unistd.h> header file, the full UIC is returned. For 
example, if the UIC is [313, 31] then 20512799 (31 + 313 * 65536) is returned. 


With POSIX style IDs enabled, geteuid returns the effective user ID of the 
calling process, and getuid returns the real user ID of the calling process. 


To enable/disable POSIX style IDs, see Section 1.7. 
See also getegid and getgid. 


Return Value 


x The real user ID (POSIX IDs enabled), or the 
member number from the current UIC or the full 
UIC (POSIX IDs disabled). 
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getw 


Format 


Argument 


Description 


Returns characters from a specified file. 


#include <stdio.h> 
int getw (FILE *file_ptr): 


file_ptr 
A pointer to the file to be accessed. 


The getw function returns the next four characters from the specified input file as 
an int. 


Return Values 
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x The next four characters, in an int. 


EOF Indicates that the end-of-file was encountered 
during the retrieval of any of the four characters 
and all four characters were lost. Since EOF is 
an acceptable integer, use feof and ferror to 
check the success of the function. 


getwc 


getwc 
Reads the next character from a specified file, and converts it to a wide-character 
code. 
Format 
#include <wchar.h> 
wint_t getwc (FILE *file_ptr); 
Argument 
file_ptr 
A pointer to the file to be accessed. 
Description 


Since getwc is implemented as a macro, a file pointer argument with side effects 
(for example getwc (*f++)) might be evaluated incorrectly. In such a case, use 
the fgetwc function instead. See the fgetwc function. 


Return Values 


n The returned character. 


WEOF Indicates the end-of-file or an error. If an error 
occurs, the function sets errno. For a list of the 
values set by this function, see fgetwc. 
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getwchar 


getwchar 

Reads a single wide character from the standard input (stdin). 
Format 

#include §<wchar.h> 

wint_t getwchar (void); 
Description 


The getwchar function is identical to fgetwc(stdin). 


Return Values 


x The next character from stdin, converted to 
wint t. 
WEOF Indicates the end-of-file or an error. If an error 


occurs, the function sets errno. For a list of the 
values set by this function, see fgetwe. 
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getyx 


getyx 


Format 


Arguments 


Puts the (y,x) coordinates of the current cursor position on win in the variables y 


and x. 


#include <curses.h> 
getyx (WINDOW *win, int y, int x); 


win 


Must be a valid lvalue. 


4 
Must be a valid lvalue. 


Must be a pointer to the window. 
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Glob apna, 164 


Returns a list of existing files for a user supplied pathname (with optional 
wildcards). 


Format 
#include <glob.h> 


int glob (const char “pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob); 


Function Variants 


The glob function has variants named glob32 and _globé4 for use with 32-bit 
and 64-bit pointer sizes, respectively. See Section 1.10 for more information on 
using pointer-size-specific functions. 


Arguments 


pattern 
The pattern string to match with accessible files and pathnames. This pattern 
can have wildcards. 


flags 
Controls the customizable behavior of the glob function. 


errfunc 
An optional function that, if specified, is called when the glob function detects an 
error condition, or if not specified, is NULL. 


epath 
First argument of the optional errfunc function, epath is the pathname that failed 
because a directory could not be opened or read. 


eerrno 

Second argument of the optional errfunc function, eerrno is the errno value from 
a failure specified by the epath argument as set by the opendir, readdir, or stat 
functions. 


pglob 

Pointer to a glob t structure that returns the matching accessible existing 
filenames. The structure is allocated by the caller. The array of structures 
containing the located filenames that match the pattern argument are stored by 
the glob function into the structure. The last entry is a NULL pointer. 


The structure type glob _t is defined in the <glob.h> header file and includes at 
least the following members: 


size t gl _pathc //Count of paths matched by pattern. 
char ** gl pathv //Pointer to a list of matched pathnames. 
size t gl offs //Slots to reserve at the beginning of gl _pathv. 
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Description 


glob (ipra, 164 


The glob function constructs a list of accessible files that match the pattern 
argument. 


The glob function operates in one of two modes: UNIX mode or OpenVMS mode. 


You can select UNIX mode explicitly by enabling the feature logical 
DECC$GLOB_UNIX_STYLE, which is disabled by default. 


The glob function defaults to OpenVMS mode unless one of the following 
conditions is met (in which case glob uses UNIX mode): 


e The DECC$GLOB_UNIX_STYLE is enabled. 
e The DECC$FILENAME_UNIX_ONLY feature logical is enabled. 


e The glob function checks the specified pattern for pathname indications, such 
as directory delimiters, and determines it to be a UNIX style pathname. 


OpenVMS mode 


This mode allows an OpenVMS programmer to give an OpenVMS style pattern 
to the glob function and get expected OpenVMS style output. The OpenVMS 
style pattern is what a user would expect from DCL commands or as input to the 
SYS$PARSE and SYS$SEARCH system routines. 


In this mode, you can use any of the expected OpenVMS wildcards (see the 
OpenVMS documentation for additional information). 


OpenVMS mode does not support the UNIX wildcard ?, or [] pattern matching. 
OpenVMS users expect [] to be available as directory delimiters. 


Some additional behavior differences between OpenVMS mode and UNIX mode: 


e OpenVMS mode outputs full file specifications, not relative ones, as in UNIX 
mode. 


e The GLOB_MARK flag is ignored in OpenVMS mode because it is not 
meaningful to append a slash (/) to a directory on OpenVMS. 


For example: 


Sample pattern input Sample output 
[.SUBDIR1]A.TXT DEV: [DIR.SUBDIR1]A.TXT;1 
[.SUB*]%.* DEV: [DIR.SUBDIR1]A.TXT;1 
UNIX mode 


You can enable this mode explicitly with: 
$ DEFINE DECCSGLOB UNIX STYLE ENABLE 


UNIX mode is also enabled if the DECC$FILENAME UNIX ONLY feature 
logical is set, or if the glob function determines that the specified pattern looks 
like a UNIX style pathname. 


In UNIX mode, the glob function follows the X/Open specification where possible. 


For example: 


Sample pattern input Sample output 
./a/b/c ./a/b/e 
./?/b/* ./a/b/c 

[a-c] c 
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Standard Description 


The glob function matches all accessible pathnames against this pattern and 
develops a list of all pathnames that match. To have access to a pathname, the 
glob function requires search permission on every component of a pathname 
except the last, and read permission on each directory of any filename component 
of the pattern argument. 


The glob function stores the number of matched pathnames and a pointer to a 
list of pointers to pathnames in the pglob argument. The pathnames are sorted, 
based on the setting of the LC_COLLATE category in the current locale. The 
first pointer after the last pathname is NULL. If the pattern does not match any 
pathnames, the returned number of matched pathnames is 0. 


It is the caller’s responsibility to create the structure pointed to by the pglob 
argument. The glob function allocates other space as needed. The globfree 
function frees any space associated with the pglob argument as a result of a 
previous call to the glob function. 


The flags argument is used to control the behavior of the glob function. The flags 
value is the bitwise inclusive OR (| ) of any of the following constants, which are 
defined in the <glob.h> header file: 


GLOB_APPEND Appends pathnames located with this call to any 
pathnames previously located. 


GLOB_DOOFFS Uses the gl_offs structure to specify the number of NULL 
pointers to add to the beginning of the gl_pathv component 
of the pglob argument. 


GLOB_ERR Causes the glob function to return when it encounters a 
directory that it cannot open or read. If the GLOB_ERR 
flag is not set, the glob function continues to find matches 
if it encounters a directory that it cannot open or read. 


GLOB_MARK Specifies that each pathname that is a directory should 
have a slash (/) appended. GLOB_MARK is ignored in 
OpenVMS mode because it is not meaningful to append a 
slash to a directory on OpenVMS systems. 

GLOB_NOCHECK If the pattern argument does not match any pathname, 
then the glob function returns a list consisting only of the 
pattern argument, and the number of matched pathnames 


is 1. 
GLOB_ If the GLOB_NOESCAPE flag is set, a backslash ( \ ) 
NOESCAPE cannot be used to escape metacharacters. 


The GLOB_APPEND flag can be used to append a new set of pathnames to those 
found in a previous call to the glob function. The following rules apply when 
two or more calls to the glob function are made with the same value of the pglob 
argument, and without intervening calls to the globfree function: 


e If the application sets the GLOB_DOOFFS flag in the first call to the glob 
function, then it is also set in the second call, and the value of the gl_offs 
field of the pglob argument is not modified between the calls. 


e Ifthe application did not set the GLOB_DOOFFS flag in the first call to the 
glob function, then it is not set in the second call. 


glob (ipra, 164 


e After the second call, pglob->gl_pathv points to a list containing the 
following: 


— Zero or more NULLs, as specified by the GLOB_DOOFFS flag and 
pglob->gl_offs. 


- Pointers to the pathnames that were in the pglob->g1_pathv list before 
the call, in the same order as after the first call to the glob function. 


— Pointers to the new pathnames generated by the second call, in the 
specified order. 


e The count returned in the pglob->g1_offs argument is the total number of 
pathnames from the two calls. 


e The application should not modify the pglob->gl_pathc or pglob->gl_pathv 
fields between the two calls. 


On successful completion, the glob function returns a value of 0 (zero). 

The pglob->gl_pathc field returns the number of matched pathnames and 
the pglob->g1_pathv field contains a pointer to a NULL-terminated list of 
matched and sorted pathnames. If the number of matched pathnames in the 
pglob->gl_pathc argument is 0 (zero), the pointer in the pglob->gl_pathv 
argument is undefined. 


If the glob function terminates because of an error, the function returns one 

of the nonzero constants GLOB_ABORTED, GLOB_NOMATCH, or GLOB_ 
NOSPACE, defined in the <glob.h> header file. In this case, the pglob argument 
values are still set as defined above. 


If, during the search, a directory is encountered that cannot be opened or read 
and the errfunc argument value is not NULL, the glob function calls errfunc with 
the two arguments epath and eerno: 


epath—The pathname that failed because a directory could not be opened or 
read. 

eerno—The errno value from a failure specified by the epath argument as set 
by the opendir, readdir, or stat functions. 


If errfunc is called and returns nonzero, or if the GLOB_ERR flag is set in flags, 
the glob function stops the scan and returns GLOB_ABORTED after setting the 
pglob argument to reflect the pathnames already scanned. If GLOB_ERR is not 
set and either errfunc is NULL or errfunc returns zero, the error is ignored. 


No errno values are returned. 


See also globfree, readdir, and stat. 


Return Values 


0 Successful completion. 

GLOB_ABORTED The scan was stopped because GLOB_ERROR 
was set or errfunc returned a nonzero value. 

GLOB_NOMATCH The pattern does not match any existing 
pathname, and GLOB_NOCHECK was not 
set in flags. 

GLOB_NOSPACE An attempt to allocate memory failed. 
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globfree 


Frees any space associated with the pglob argument resulting from a previous 
call to the glob function. 
Format 
#include <glob.h> 
void globfree (glob_t *pglob); 


Function Variants 
The globfree function has variants named globfree32 and globfreeé4 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 

Argument 
pglob 
Pointer to a previously allocated glob _t structure. 

Description 


The globfree function frees any space associated with the pglob argument 
resulting from a previous call to the glob function. The globfree function 
returns no value. 
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gmtime, gmtime_r 


Format 


Converts time units to the broken-down UTC time. 


#include <time.h> 
struct tm *gmtime (const time_t *timer); 


struct tm *gmtime_r (const time_t “timer, struct tm *result); SO POSIX-1) 


Function Variants 


Arguments 


Description 


Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the gmtime_r function 
that is equivalent to the behavior before OpenVMS Version 7.0. 


timer 
Points to a variable that specifies a time value in seconds since the Epoch. 


result 
A pointer to a tm structure where the result is stored. 


The tm structure is defined in the <time.h> header, and is also shown in 
Table REF—4 in the description of localtime. 


The gmtime and gmtime_r functions convert the time (in seconds since the Epoch) 
pointed to by timer into a broken-down time, expressed as Coordinated Universal 
Time (UTC), and store it in a tm structure. 


The difference between the gmtime_r and gmtime functions is that the former 
puts the result into a user-specified tm structure where the result is stored. The 
latter puts the result into thread-specific static memory allocated by the HP C 
RTL, and which is overwritten by subsequent calls to gmtime; you must make a 
copy if you want to save it. 


On success, gmtime returns a pointer to the tm structure; gmtime_r returns its 
second argument. On failure, these functions return the NULL pointer. 


Note 


Generally speaking, UTC-based time functions can affect in-memory time- 
zone information, which is processwide data. However, if the system time 
zone remains the same during the execution of the application (which is 
the common case) and the cache of timezone files is enabled (which is the 
default), then the _r variant of the time functions asctime_r, ctime_r, 
gmtime_r and localtime_r, is both thread-safe and AST-reentrant. 


If, however, the system time zone can change during the execution of 

the application or the cache of timezone files is not enabled, then both 
variants of the UTC-based time functions belong to the third class of 

functions, which are neither thread-safe nor AST-reentrant. 
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Return Values 


x Pointer to a tm structure. 
NULL Indicates an error; errno is set to the following 
value: 


e EINVAL — The timer argument is NULL. 
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gsignal 


Format 


Arguments 


Description 


Generates a specified software signal, which invokes the action routine 
established by a signal, ssignal, or sigvec function. 


#include <signal.h> 


int gsignal (int sig [, int sigcode)); 


sig 

The signal to be generated. 

sigcode 

An optional signal code. For example, signal SIGFPE—the arithmetic trap 


signal—has 10 different codes, each representing a different type of arithmetic 
trap. 


The signal codes can be represented by mnemonics or numbers. The arithmetic 
trap codes are represented by the numbers 1 to 10, but the SIGILL codes 

are represented by the numbers 0 to 2. The code values are defined in the 
<signal.h> header file. See Tables 4—4 and 4—5 for a list of signal mnemonics, 
codes, and corresponding OpenVMS exceptions. 


Calling the gsignal function has one of the following results: 


e Ifgsignal specifies a sig argument that is outside the range defined in the 
<signal.h> header file, then gsignal returns 0 and sets errno to EINVAL. 


e If signal, ssignal, or sigvec establishes SIG_DFL (default action) for 
the signal, then gsignal does not return. The image is exited with the 
OpenVMS error code corresponding to the signal. 


e If signal, ssignal, or sigvec establishes SIG_IGN (ignore signal) as the 
action for the signal, then gsignal returns its argument, sig. 


e signal, ssignal, or sigvec must be used to establish an action routine for the 
signal. That function is called and its return value is returned by gsignal. 


See Chapter 4 for more information. 


See also raise, signal, ssignal, and sigvec. 


Return Values 


0 Indicates a sig argument that is outside the 
range defined in the <signal.h> header file; 
errno is set to EINVAL. 

sig Indicates that SIG_IGN (ignore signal) has been 
established as the action for the signal. 
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x Indicates that signal, ssignal, or sigvec has 
established an action function for the signal. 
That function is called, and its return value is 
returned by gsignal. 
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hypot 


Format 


Arguments 


Description 


Returns the length of the hypotenuse of a right triangle. 


#include <math.h> 
double hypot (double x, double y); 
float hypotf (float x, float y); (Alpha, 164) 


long double hypotl (long double x, long double y); (Alpha, 164) 


4 
A real value. 


A real value. 


The hypot functions return the length of the hypotenuse of a right triangle, where 
x and y represent the perpendicular sides of the triangle. The length is calculated 
as: 


sqrt(x + y?) 


On overflow, the return value is undefined, and errno is set to ERANGE. 


Return Values 


x The length of the hypotenuse. 

HUGE_VAL Overflow occurred; errno is set to ERANGE. 
0 Underflow occurred; errno is set to ERANGE. 
NaN x or y is NaN; errno is set to EDOM. 
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iconv 


Converts characters coded in one codeset to characters coded in another codeset. 


Format 
#include <iconv.h> 


size_t iconv (iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); 


Arguments 


cd 
A conversion descriptor. This is returned by a successful call to iconv_open. 


inbuf 
A pointer to a variable that points to the first character in the input buffer. 


inbytesleft 

Initially, this argument is a pointer to a variable that indicates the number of 
bytes to the end of the input buffer (inbuf). When the conversion is completed, 
the variable indicates the number of bytes in inbuf not converted. 


outbuf 
A pointer to a variable that points to the first available byte in the output buffer. 
The output buffer contains the converted characters. 


outbytesleft 

Initially, this argument is a pointer to a variable that indicates the number of 
bytes to the end of the output buffer (owtbuf). When the conversion is completed, 
the variable indicates the number of bytes left in owtbuf. 


Description 


The iconv function converts characters in the buffer pointed to by inbuf to 
characters in another code set. The resulting characters are stored in the buffer 
pointed to by outbuf. The conversion type is specified by the conversion descriptor 
cd. This descriptor is returned from a successful call to iconv_open. 


If an invalid character is found in the input buffer, the conversion stops after 
the last successful conversion. The variable pointed to by inbytesleft is updated 
to reflect the number of bytes in the input buffer that are not converted. The 
variable pointed to by outbytesleft is updated to reflect the number of bytes 
remaining in the output buffer. 


Return Values 
x Number of nonidentical conversions performed. 


Indicates successful conversion. In most cases, 0 
is returned. 
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iconv 


(size_t) —-1 Indicates an error condition. The function sets 
errno to one of the following: 


EBADF — The cd argument is not a valid 
conversion descriptor. 


EILSEQ — The conversion stops when an 
invalid character detected. 


E2BIG — The conversion stops because of 
insufficient space in the output buffer. 


EINVAL — The conversion stops because of 
an incomplete character at the end of the 
input buffer. 
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iconv_close 


Deallocates a specified conversion descriptor and the resources allocated to the 


descriptor. 
Format 

#include <iconv.h> 

int iconv_close (iconv_t cd); 
Argument 


cd 
The conversion descriptor to be deallocated. A conversion descriptor is returned 
by a successful call to iconv_open. 


Return Values 


0 Indicates that the conversion descriptor was 
successfully deallocated. 

-1 Indicates an error occurred. The function sets 
errno to one of the following: 


e EBADF - The cd argument is not a valid 
conversion descriptor. 


e EVMSERR — Nontranslatable OpenVMS 
error occur. vaxcSerrno contains the VMS 
error code. 
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iconv_open 


Allocates a conversion descriptor for a specified codeset conversion. 


Format 


#include <iconv.h> 


iconv_t iconv_open (const char *tocode, const char *fromcode); 


Arguments 


tocode 


The name of the codeset to which characters are converted. 


fromcode 


The name of the source codeset. See Chapter 10 for information on obtaining a 
list of currently available codesets or for details on adding new codesets. 


Return Values 


x A conversion descriptor. Indicates the call was 
successful. This descriptor is used in subsequent 
calls to iconv 


(iconv_t) —1 Indicates an error occurred. The function sets 
errno to one of the following: 


Example 


#include <stdio.h> 
#include <iconv.h> 
#include <errno.h> 


int main() 


EMFILE — The process does not have enough 
I/O channels to open a file. 


ENOMEM - Insufficient space is available. 


EINVAL — The conversion specified by 
fromcode and tocode is not supported. 


EVMSERR — Nontranslatable OpenVMS 
error occur. vaxcSerrno contains the 
OpenVMS error code. A value of SS$_ 
BADCHKSUM in vaxcSerrno indicates 

that a conversion table file was found, but 
its contents is corrupted. A value of SS$_ 
IDMISMATCH in vaxcS$errno indicates that 
the conversion table file version does not 
match the version of the C Run-Time Library. 


/* Declare variables to be used */ 
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iconv_open 
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char fromcodeset [30]; 

char tocodeset [30] ; 

int iconv_opened; 

iconv_t iconv_struct; /* Iconv descriptor +7 


/* Initialize variables */ 


sprintf (fromcodeset, "DECHANYU") ; 
sprintf (tocodeset, "EUCTW") ; 
iconv_opened = FALSE; 


/* Attempt to create a conversion descriptor for the */ 


/* codesets specified. If the return value from */ 

/* iconv_open is -1 then an error has occurred. */ 

/* Check the value of errno. */ 

if ((iconv_struct = iconv_open(tocodeset, fromcodeset) ) 
== (iconv_t) - 1) 

/* Check the value of errno */ 


switch (errno) { 
case EMFILE: 
case ENFILE: 


break; 


case ENOMEM: 
printf ("Not enough memory\n") ; 
break; 


case EINVAL: 
printf ("Unsupported conversion\n") ; 
break; 


default: 
printf ("Unexpected error from iconv_open\n") ; 
break; 


} 
else 
/* Successfully allocated a conversion descriptor 
iconv_opened = TRUE; 
/* Was a conversion descriptor allocated 
if (iconv_opened) { 


/* Attempt to deallocate the conversion descriptor. 
/* If iconv_close returns -1 then an error has 
/* occurred. 


if (iconv_close(iconv struct) == -1) { 
/* An error occurred. Check the value of errno 


switch (errno) { 
case EBADF: 


printf("Too many iconv conversion files open\n"); 


! 


a 


ay 


printf ("Conversion descriptor is invalid\n"); 


break; 
default: 


printf ("Unexpected error from iconv_close\n") ; 


break; 


} 
} 


return (EXIT FAILURE) ; 


Hlogb (ipha, 164) 


HOgb caipha, 164) 


Returns the exponent part of its argument. 


Format 

#include <math.h> 

int ilogb (double x); 

int ilogbf (float x); 

int ilogbl (long double x); 
Argument 

x 

A real value. 
Description 


The ilogb functions return the exponent part of their argument x. Formally, 
the return value is the integral part of logr |x | as a signed integral value, for 
non-zero x, where r is the radix of the machine’s floating-point arithmetic, which 
is the value of FLT_RADIX defined in <float.h>. 


Return Values 


n Upon success, the exponent part of x as a signed 
integer value. These functions are equivalent 
to calling the corresponding logb function and 
casting the returned value to type int. 
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[w]inch 


[w]inch 
Return the character at the current cursor position on the specified window 
without making changes to the window. The inch function acts on the stdscr 
window. 

Format 
#include <curses.h> 
char inch( ); 
char winch (WINDOW *win); 

Argument 


win 
A pointer to the window. 


Return Values 


x The returned character. 
ERR Indicates an input error. 
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index 


index 
Searches for a character in a string. 


Format 
#include <strings.h> 


char “index (const char *s, int c); 


Function Variants 


The index function has variants named index32 and indexé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Arguments 


s 
The string to search. 


c 
The character to search for. 


Description 


The index function is identical to the strchr function, and is provided for 
compatibility with some UNIX implementations. 
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initscr 


initscr 
Initializes the terminal-type data and all screen functions. You must call initscr 
before using any of the curses functions. 
Format 
#include <curses.h> 
void initscr (void); 
Description 


The OpenVMS Curses version of the initscr function clears the screen before 
doing the initialization. The BSD-based Curses version does not. 
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initstate 


initstate 


Format 


Arguments 


Description 


Initializes random-number generators. 


#include <stdlib.h> 


char *initstate (unsigned int seed, char “state, int size); 


seed 
An initial seed value. 


state 
Pointer to an array of state information. 


size 
The size of the state information array. 


The initstate function initializes random-number generators. It lets you 
initialize, for future use, a state array passed as an argument. The size, in bytes, 
of the state array is used by the initstate function to decide how sophisticated a 
random-number generator to use; the larger the state array, the more random the 
numbers. 


Values for the amount of state information are 8, 32, 64, 128, and 256 bytes. 
Amounts less than 8 bytes generate an error, while other amounts are rounded 
down to the nearest known value. 


The seed argument specifies a starting point for the random-number sequence 
and provides for restarting at the same point. The initstate function returns a 
pointer to the previous state information array. 


Once you initialize a state, the setstate function allows rapid switching between 
states. The array defined by the state argument is used for further random- 
number generation until the initstate function is called or the setstate 
function is called again. The setstate function returns a pointer to the previous 
state array. 


After initialization, you can restart a state array at a different point in one of two 
ways: 


e Use the initstate function with the desired seed argument, state array, and 
size of the array. 


e Use the setstate function with the desired state, followed by the srandom 
function with the desired seed. The advantage of using both functions is that 
you do not have to save the state array size once you initialize it. 


See also setstate, srandom, and random. 
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initstate 


Return Values 


A pointer to the previous state array information. 


0 Indicates an error. Call made with less than 8 
bytes of state information. Further specified in 
the global errno. 
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[w]insch 


[w]insch 

Insert a character at the current cursor position in the specified window. The 

insch function acts on the stdscr window. 
Format 

#include <curses.h> 

int insch (char ch); 

int winsch (WINDOW ‘win, char ch); 
Arguments 

win 

A pointer to the window. 

ch 

The character to be inserted. 
Description 


After the character is inserted, each character on the line shifts to the right, and 
the last character in the line is deleted. For more information, see the scrollok 
function. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally. 
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[w]insertin 


[w]insertin 


Insert a line above the line containing the current cursor position. The insertln 
function acts on the stdscr window. 


Format 

#include <curses.h> 

int insertin( ); 

int winsertIn (WINDOW *win); 
Argument 

win 

A pointer to the window. 
Description 


The current line and every line below it shifts down, and the bottom line 
disappears. The inserted line is blank and the current (y,x) coordinates remain 
the same. For more information, see the scrollok function. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally. 
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[w]insstr 


[w]insstr 


Insert a string at the current cursor position in the specified window. The insstr 
function acts on the stdscr window. 


Format 
#include <curses.h> 


int insstr (char *str); 
int winsstr (WINDOW *win, char *str); 


Arguments 
win 
A pointer to the window. 


str 
A pointer to the string to be inserted. 


Description 


Each character after the string shifts to the right, and the last character 
disappears. These functions are specific to HP C for OpenVMS Systems and 
are not portable. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally. For more information, see the 
scrollok function. 
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isalnum 


isalnum 
Indicates if a character is classed either as alphabetic or as a digit in the 
program’s current locale. 
Format 
#include <ctype.h> 
int isalnum (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If alphanumeric. 
0 If not alphanumeric. 
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isalpha 


isalpha 
Indicates if a character is classed as an alphabetic character in the program’s 
current locale. 
Format 
#include <ctype.h> 
int isalpha (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If alphabetic. 
0 If not alphabetic. 
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isapipe 


isapipe 
Indicates if a specified file descriptor is associated with a pipe. 
Format 
#include <unixio.h> 
int isapipe (int file_desc); 
Argument 
file_desc 
A file descriptor. 
Description 


For more information about pipes, see Chapter 5. 


Return Values 


Indicates an association with a pipe. 
Indicates no association with a pipe. 


—1 Indicates an error (for example, if the file 
descriptor is not associated with an open file). 
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isascii 


isasclii 

Indicates if a character is an ASCII character. 
Format 

#include <ctype.h> 

int isascii (int character); 
Argument 


character 
An object of type char. 


Return Values 


nonzero If ASCII. 
0 If not ASCII. 
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isatty 


isatty 

Indicates if a specified file descriptor is associated with a terminal. 
Format 

#include <unistd.h> 

int isatty (int file_desc): 
Argument 


file_desc 
A file descriptor. 


Return Values 


1 If the file descriptor is associated with a 
terminal. 

0 If the file descriptor is not associated with a 
terminal. 

—1 Indicates an error (for example, if the file 


descriptor is not associated with an open file). 
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iscntrl 


iscntrl 
Indicates if a character is classed as a control character in the program’s current 
locale. 
Format 
#include <ctype.h> 
int iscntrl (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If a control character. 
0 If not a control character. 
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isdigit 


isdigit 

Indicates if a character is classed as a digit in the program’s current locale. 
Format 

#include <ctype.h> 

int isdigit (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If a decimal digit. 
0 If not a decimal digit. 
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isgraph 


isgraph 
Indicates if a character is classed as a graphic character in the program’s current 
locale. 
Format 
#include <ctype.h> 
int isgraph (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If a graphic character. 
0 If not a graphic character. 
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islower 


islower 
Indicates if a character is classed as a lowercase character in the program’s 
current locale. 
Format 
#include <ctype.h> 
int islower (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If a lowercase alphabetic character. 
0 If not a lowercase alphabetic character. 
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isnan (ipha, 164) 


isnan (Alpha, 164) 


Tests for a NaN. Returns 1 if the argument is NaN; 0 if not. 


Format 

#include <math.h> 

int isnan (double x); 

int isnanf (float x); 

int isnanl (long double x); 
Argument 

x 

A real value. 
Description 


The isnan functions return the integer value 1 (TRUE) if x is NaN (the IEEE 
floating point reserved not-a-number value); otherwise, they return the value 0 
(FALSE). 
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isprint 


isprint 
Indicates if a character is classed as a printing character in the program’s current 
locale. 
Format 
#include <ctype.h> 
int isprint (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If a printing character. 
0 If not a printing character. 
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ispunct 


ispunct 
Indicates if a character is classed as a punctuation character in the program’s 
current locale. 
Format 
#include <ctype.h> 
int ispunct (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If a punctuation character. 
0 If not a punctuation character. 
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isspace 


isspace 
Indicates if a character is classed as white space in the program’s current locale; 
that is, if it is an ASCII space, tab (horizontal or vertical), carriage-return, 
form-feed, or new-line character. 

Format 
#include <ctype.h> 
int isspace (int character); 

Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If a white-space character. 
0 If not a white-space character. 


REF-340 


isupper 


isupper 
Indicates if a character is classed as an uppercase character in the program’s 
current locale. 
Format 
#include <ctype.h> 
int isupper (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char or must equal the value of the macro EOF. If it has any other 
value, the behavior is undefined. 


Return Values 


nonzero If an uppercase alphabetic character. 
0 If not an uppercase alphabetic character. 
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iswalnum 


iswalnum 
Indicates if a wide character is classed either as alphabetic or as a digit in the 
program’s current locale. 
Format 
#include <wctype.h> (7so ©) 
#include <wchar.h> ~xPG4) 
int iswalnum (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of character must be representable as a 
wchar_t in the current locale, or must equal the value of the macro WEOF. If it 
has any other value, the behavior is undefined. 


Return Values 


nonzero If alphanumeric. 
0 If not alphanumeric. 
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iswalpha 


iswalpha 
Indicates if a wide character is classed as an alphabetic character in the 
program’s current locale. 
Format 
#include <wctype.h> so Cc) 
#include <wchar.h> (xPG4) 
int iswalpha (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar_t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If alphabetic. 
0 If not alphabetic. 
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iswentrl 


iswentrl 
Indicates if a wide character is classed as a control character in the program’s 
current locale. 
Format 
#include <wctype.h> (zso ©) 
#include <wchar.h> ~xPG4) 
int iswentrl (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a control character. 
0 If not a control character. 
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iswctype 


iswctype 


Format 


Arguments 


Description 


Indicates if a wide character has a specified property. 


#include <wctype.h> so Cc) 
#include <wchar.h> ~xPG4) 


int iswctype (wint_t wc, wctype_t wc_prop); 


wc 

An object of type wint_t. The value of wc must be representable as a valid 
wide-character code in the current locale, or must equal the value of the macro 
WEOF. If it has any other value, the behavior is undefined. 


wc_prop 
A valid property name in the current locale. This is set up by calling the wctype 
function. 


The iswctype function tests whether wc has the character-class property wc_prop. 
Set wc_prop by calling the wctype function. 


See also wctype. 


Return Values 


Example 


nonzero If the character has the property wc_prop. 
0 If the character does not have the property 
we_prop. 


#include <locale.h> 
#include <wchar.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
#include <ctype.h> 


/* This test will set up the "upper" character class using */ 
/* wetype() and then verify whether the characters ‘a’ and ‘A’ */ 
/* are members of this class */ 


#include <stdlib.h> 


main () 


{ 


wchar_t w_charl, 
w_char2; 
wctype t ret val; 


char *charl = "a"; 
char *char2 = "A"; 


ret_val = wctype ("upper") ; 
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iswctype 
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/* Convert charl to wide-character format - w_charl */ 


if (mbtowc(&w charl, charl, 1) == -1) { 
perror ("mbtowc") ; 
exit (EXIT_FAILURE) ; 


if (iswetype((wint_t) w_charl, ret_val)) 
printf("[%C] is a member of the character class upper\n", 


w_charl) ; 
else 
printf("[%C] is not a member of the character class upper\n", 
w_char1) ; 


/* Convert char2 to wide-character format - w_char2 */ 


if (mbtowc(&w char2, char2, 1) == -1) { 
perror ("mbtowc") ; 
exit (EXIT_FAILURE) ; 


if (iswetype((wint_t) w_char2, ret_val)) 
printf("[%C] is a member of the character class upper\n", 


w_char2) ; 

else 

printf("[%C] is not a member of the character class upper\n", 
w_char2) ; 


Running the example program produces the following result: 


[a] is not a member of the character class upper 
[A] is a member of the character class upper 


iswdigit 


iswdigit 

Indicates if a wide character is classed as a digit in the program’s current locale. 
Format 

#include <wctype.h> so Cc) 

#include <wchar.h> (xPG4) 

int iswdigit (wint_t we): 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar_ t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a decimal digit. 
0 If not a decimal digit. 
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iswgraph 


iswgraph 
Indicates if a wide character is classed as a graphic character in the program’s 
current locale. 
Format 
#include <wctype.h> (7so c) 
#include <wchar.h> ~xPG4) 
int iswgraph (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a graphic character. 
0 If not a graphic character. 
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iswlower 


iswlower 
Indicates if a wide character is classed as a lowercase character in the program’s 
current locale. 
Format 
#include <wctype.h> so c) 
#include <wchar.h> (xPG4) 
int iswlower (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar_t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a lowercase character. 
0 If not a lowercase character. 


REF-349 


iswprint 


iswprint 
Indicates if a wide character is classed as a printing character in the program’s 
current locale. 
Format 
#include <wctype.h> (zso ©) 
#include <wchar.h> ~xPG4) 
int iswprint (wint_t we): 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a printing character. 
0 If not a printing character. 
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iswpunct 


iswpunct 
Indicates if a wide character is classed as a punctuation character in the 
program’s current locale. 
Format 
#include <wctype.h> so Cc) 
#include <wchar.h> (xPG4) 
int iswpunct (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar_t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a punctuation character. 
0 If not a punctuation character. 
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iswspace 


iswspace 
Indicates if a wide character is classed as a space character in the program’s 
current locale. 
Format 
#include <wctype.h> (7so ©) 
#include <wchar.h> ~xPG4) 
int iswspace (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar_t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a white-space character. 
0 If not a white-space character. 
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iswupper 


iswupper 
Indicates if a wide character is classed as an uppercase character in the program’s 
current locale. 
Format 
#include <wctype.h> so Cc) 
#include <wchar.h> (xPG4) 
int iswupper (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar_t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If an uppercase character. 
0 If not an uppercase character. 
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iswxdigit 


iswxdigit 
Indicates if a wide character is a hexadecimal digit (0 to 9, A to F, or a to f) in the 
program’s current locale. 
Format 
#include <wctype.h> (7so ©) 
#include <wchar.h> ~xPG4) 
int iswxdigit (wint_t we); 
Argument 


wc 

An object of type wint_t. The value of wc must be representable as a wchar_t 
in the current locale, or must equal the value of the macro WEOF. If it has any 
other value, the behavior is undefined. 


Return Values 


nonzero If a hexadecimal digit. 
0 If not a hexadecimal digit. 
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isxdigit 


isxdigit 
Indicates if a character is a hexadecimal digit (0 to 9, A to F, or a to f) in the 
program’s current locale. 
Format 
#include <ctype.h> 
int isxdigit (int character); 
Argument 


character 

An object of type int. The value of character must be representable as an 
unsigned char in the current locale, or must equal the value of the macro EOF. If 
it has any other value, the behavior is undefined. 


Return Values 


nonzero If a hexadecimal digit. 
0 If not a hexadecimal digit. 
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jo, ji 5 jn (Alpha, 164) 


JO, j1, JIN cipra, 164) 


Format 


Arguments 


Description 


Compute Bessel functions of the first kind. 


#include <math.h> 

double j0 (double x); 

float jOf (float x); 

long double j0! (long double x); 
double j1 (double x); 

float j1f (float x); 

long double j1! (long double x); 
double jn (int n, double x); 
float jnf (int n, float x); 


long double jn! (int n, long double x); 


x 
A real value. 


n 
An integer. 


The j0 functions return the value of the Bessel function of the first kind of order 
The j1 functions return the value of the Bessel function of the first kind of order 


The jn functions return the value of the Bessel function of the first kind of order 


The j1 and jn functions can result in an underflow as x gets small. The largest 
value of x for which this occurs is a function of n. 


Return Values 


REF-356 


The relevant Bessel value of x of the first kind. 


0 The value of the x argument is too large, or 
underflow occurred; errno is set to ERANGE. 
NaN x is NaN; errno is set to EDOM. 


jrand48 


jrand48 


Format 


Argument 


Description 


Generates uniformly distributed pseudorandom-number sequences. Returns 
48-bit signed, long integers. 


#include <stdlib.h> 
long int jrand48 (unsigned short int xsubi[3)); 


xsubi 
An array of three short ints that form a 48-bit integer when concatentated 
together. 


The jrand48 function generates pseudorandom numbers using the linear 
congruential algorithm and 48-bit integer arithmetic. 


The function returns signed long integers uniformly distributed over the range of 
y values, such that —2°! < y < 2°!. 


The function works by generating a sequence of 48-bit integer values, Xi, 
according to the linear congruential formula: 


Xn+1 = (aXn+c)mod m n >= 0 


The argument m equals 24°, so 48-bit integer arithmetic is performed. Unless you 
invoke the lcong48 function, the multiplier value a and the addend value c are: 


a 
Cc 


5DEECE66D16 = 2736731631558 
Big = 138 


The jrand48 function requires that the calling program pass an array as the 
xsubi argument, which for the first call must be initialized to the initial value 
of the pseudorandom-number sequence. Unlike the drand48 function, it is not 
necessary to call an initialization function prior to the first call. 


By using different arguments, jrand48 allows separate modules of a large 
program to generate several independent sequences of pseudorandom numbers. 
For example, the sequence of numbers that one module generates does not depend 
upon how many times the function is called by other modules. 


Return Value 


n Signed, long integers uniformly distributed over 
the range —23! < y < 231, 
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kill 


kill 


Format 


Arguments 


Description 


Sends a signal to the process specified by a process ID. 


#include <signal.h> 


int kill (int pid, int sig); 


pid 
The process ID. 


sig 
The signal code. 


The kill function is restricted to C and C++ programs that include the main 
function. 


The kill function sends a signal to a process, as if the process had called raise. 
If the signal is not trapped or ignored by the target program, the program exits. 


OpenVMS VAX and Alpha implement different rules about what process you are 
allowed to send signals to. A program always has privileges to send a signal to a 
child started with vfork/exec. For other processes, the results are determined by 
the OpenVMS security model for your system. 


Because of an OpenVMS restriction, the kill function cannot deliver a signal to 
a target process that runs an image installed with privileges. 


Unless you have system privileges, the sending and receiving processes must 
have the same user identification code (UIC). 


On OpenVMS systems before Version 7.0, kill treats a signal value of 0 as if 
SIGKILL were specified. 


For OpenVMS Version 7.0 and higher systems, if you include <stdlib.h> and 
compile with the _POSIX_EXIT feature-test macro set, then: 


e If the signal value is 0, kill validates the process ID but does not send any 
signals. 


e Ifthe process ID is not valid, kill returns —1 and sets errno to ESRCH. 


Return Values 
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0 Indicates that kill was successfully queued. 


—1 Indicates errors. The receiving process may have 
a different UIC and you are not a system user, or 
the receiving process does not exist. 


164a (Alpha, 164 


64a (Alpha, 64) 


Format 


Argument 


Description 


Converts a long integer to a character string. 


#include <stdlib.h> 
char *I64a_ (long J); 


I 
A long integer that is to be converted to a character string. 


The a641 and 164a functions are used to maintain numbers stored in base-64 
ASCII characters: 


e a641 converts a character string to a long integer. 
e 164a converts a long integer to a character string. 


Each character used to store a long integer represents a numeric value from 0 
through 63. Up to six characters can be used to represent a long integer. 


The characters are translated as follows: 

e A period (.) represents 0. 

e A slash (/) represents 1. 

e The numbers 0 through 9 represent 2 through 11. 

e Uppercase letters A through Z represent 12 through 37. 
e Lowercase letters a through z represent 38 through 63. 


The 164a function takes a long integer and returns a pointer to a corresponding 
base-64 notation of the least significant 32 bits. 


The value returned by 164a is a pointer to a thread-specific buffer whose contents 
are overwritten on subsequent calls from the same 


See also a641. 


Return Value 


x Upon successful completion, a pointer to the 
corresponding base-64 ASCII character-string 
notation. If the / parameter is 0, 164a returns a 
pointer to an empty string. 
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labs 


labs 

Returns the absolute value of an integer as a long int. 
Format 

#include <stdlib.h> 

long int labs (long int /); 
Argument 


j 
A value of type long int. 
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Ichown 


Format 


Arguments 


Description 


Changes the user and group ownership of the specified file. 


#include <unistd.h> 


int chown (const char *file_path, uid_t file_owner, gid_t file_group); 


file_path 
The name of the file for which you want to change the owner and group IDs. 


file_owner 
The new user ID for the file. 


file_group 
The new group ID for the file. 


The lchown function changes the owner and/or group of the specified file (file_ 
path). If the file is a symbolic link, the owner of the symbolic link is modified (in 
contrast to chown which would modify the file that the symbolic link points to). 


See also symlink, unlink, readlink, realpath, and lstat. 


Return Values 


0 Successful completion. 


-1 Indicates an error. errno is set to any errno 
value returned by chown. 
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Icong48 


Icong48 


Format 


Argument 


Description 


REF-362 


Initializes a 48-bit uniformly distributed pseudorandom-number sequence. 


#include <stdlib.h> 
void Icong48 (unsigned short int param[7)); 


param 
An array that in turn specifies the initial Xz, the multiplier value a, and the 
addend value c. 


The lcong48 function generates pseudorandom numbers using the linear 
congruential algorithm and 48-bit integer arithmetic. 


You can use lcong48 to initialize the random number generator before you call 
any of the following functions: 


drand48 
lrand48 
mrand48 


The lcong48 function specifies the initial Xi value, the multiplier value a, and the 
addend value c. The param array elements specify the following: 


param|[0-2] Xi 
param[8-5] Multiplier a value 
param|[6] 16-bit addend c value 


After lcong48 has been called, a subsequent call to either srand48 or seed48 
restores the standard a and ¢ as specified previously. 


The lcong48 function does not return a value. 


See also drand48, lrand48, mrand48, srand48, and seed48. 


Idexp 


Idexp 
Returns its first argument multiplied by 2 raised to the power of its second 
argument; that is, «(2”). 
Format 
#include <math.h> 
double Idexp (double x, int n); 
float Idexp (float x, int n); (Alpha, 164) 
long double Idexp (long double x, int n); (Alpha, 164) 
Arguments 


x 
A base value of type double, float, or long double that is to be multiplied by 2”. 


n 
The integer exponent value to which 2 is raised. 


Return Values 


a(a") The first argument multiplied by 2 raised to the 
power of the second argument. 

0 Underflow occurred; errno is set to ERANGE. 

HUGE_VAL Overflow occurred; errno is set to ERANGE. 

NaN x is NaN; errno is set to EDOM. 
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Idiv 

Returns the quotient and the remainder after the division of its arguments. 
Format 

#include <stdlib.h> 

Idiv_t Idiv (long int numer, long int denom); 
Arguments 

numer 

A numerator of type long int. 

denom 

A denominator of type long int. 
Description 


The type ldiv_t is defined in the <stdlib.h> header file as follows: 
typedef struct 


long quot, rem; 
} ldiv_t; 


See also div. 
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leaveok 


Format 


Arguments 


Description 


Signals Curses to leave the cursor at the current coordinates after an update to 
the window. 


#include <curses.h> 
leaveok (WINDOW ‘win, bool boolf); 


win 
A pointer to the window. 


boolf 

A Boolean TRUE or FALSE value. If boolf is TRUE, the cursor remains in place 
after the last update and the coordinate setting on win changes accordingly. If 
boolf is FALSE, the cursor moves to the currently specified (y,x) coordinates of 
win. 


The leaveok function defaults to moving the cursor to the current coordinates of 
win. The bool type is defined in the <curses.h> header file as follows: 


#define bool int 
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Igamma aipha, 164) 


Igam Ma (ipha, 164) 


Computes the logarithm of the gamma function. 


Format 

#include <math.h> 

double Igamma (double x); 

float Igammaf (float x); 

long double Igammal (long double x); 
Argument 

x 

A real number. x cannot be 0, a negative integer, or Infinity. 
Description 


The lgamma functions return the logarithm of the absolute value of gamma of x, 
or In( | G(x) | ), where G is the gamma function. 


The sign of gamma of x is returned in the external integer variable signgam. The 
x argument cannot be 0, a negative integer, or Infinity. 


Return Values 


x The logarithmic gamma of the x argument. 

-HUGE_VAL The x argument is a negative integer; errno is 
set to ERANGE. 

NaN The x argument is NaN; errno is set to EDOM. 

0 Underflow occurred; errno is set to ERANGE. 

HUGE_VAL Overflow occurred; errno is set to ERANGE. 
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link 


link 
Creates a new link (directory entry) for an existing file. This function is supported 
only on volumes that have hard link counts enabled. 
Format 
#include <unistd.h> 
link (const char *path?, const char *path2); 
Arguments 
path1 
Pointer to a pathname naming an existing file. 
path2 
Pointer to a pathname naming the new directory entry to be created. 
Description 


The link function atomically creates a new link for the existing file, and the link 
count of the file is incremented by one. 


The link function can be used on directory files. 


If link fails, no link is created and the link count of the file remains unchanged. 


Return Values 


0 Successful completion. 


—1 Indicates an error. The function sets errno to 
one of the following values: 


EEXIST — The link named by path2 exists. 


EFTYPE — Wildcards appear in either path 1 
or path2. 


EINVAL — One or both arguments specify a 
syntactically invalid pathname. 


ENAMETOOLONG - The length of path1 or 
path2 exceeds PATH_MAX, or a pathname 
component is longer than NAME_MAX. 


EXDEV — The link named by path2 and the 
file named by path1 are on different devices. 
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localeconv 


localeconv 


Format 


Description 
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Sets the members of a structure of type struct lconv with values appropriate for 
formatting numeric quantities according to the rules of the current locale. 


#include <locale.h> 


struct Iconv “localeconv (void); 


The localeconv function returns a pointer to the lconv structure defined in the 
<locale.h> header file. This structure should not be modified by the program. It 
is overwritten by calls to localeconv, or by calls to the setlocale function that 
change the LC_NUMERIC, LC_MONETARY, or LC_ALL categories. 


The members of the structure are: 


Member 


Description 


char *decimal_point 
char *thousands_sep 
char *grouping 


char *int_curr_symbol 
char *currency_symbol 
char *mon_decimal_point 


char *mon_thousands_sep 
char *mon_grouping 

char *positive_sign 

char *negative_sign 


char int_frac_digits 


char frac_digits 


char p_cs_precedes 


The radix character. 
The character used to separate groups of digits. 


The string that defines how digits are grouped in 
nonmonetary values. 


The international currency symbol. 

The local currency symbol. 

The radix character used to format monetary 
values. 

The character used to separate groups of digits 
in monetary values. 

The string that defines how digits are grouped in 
a monetary value. 

The string used to indicate a nonnegative 
monetary value. 

The string used to indicate a negative monetary 
value. 

The number of digits displayed after the radix 
character in a monetary value formatted with 
the international currency symbol. 

The number of digits displayed after the radix 
character in a monetary value. 

For positive monetary values, this is set to 1 
if the local or international currency symbol 
precedes the number, and it is set to 0 if the 
symbol succeeds the number. 


localeconv 


Member Description 


char p_sep_by_space For positive monetary values, this is set to 0 if 
there is no space between the currency symbol 
and the number. It is set to 1 if there is a space, 
and it is set to 2 if there is a space between the 
symbol and the sign string. 


char n_cs_precedes For negative monetary values, this is set to 1 
if the local or international currency symbol 
precedes the number, and it is set to 0 if the 
symbol succeeds the number. 


char n_sep_by_space For negative monetary values, this is set to 0 if 
there is no space between the currency symbol 
and the number. It is set to 1 if there is a space, 
and it is set to 2 if there is a space between the 
symbol and the sign string. 


char p_sign_posn An integer used to indicate where the 
positive_sign string should be placed for a 
nonnegative monetary quantity. 

char n_sign_posn An integer used to indicate where the 
negative_sign string should be placed for a 
negative monetary quantity. 


Members of the structure of type char* are pointers to strings, any of which 
(except decimal_point) can point to '"", indicating that the associated value is not 
available in the current locale or is zero length. Members of the structure of type 
char are positive numbers, any of which can be CHAR_MAX, indicating that the 
associated value is not available in the current locale. CHAR_MAX is defined in 
the <limits.h> header file. 


Be aware that the value of the CHAR_MAX macro in the <limits.h> header 
depends on whether the program is compiled with the /UNSIGNED_CHAR 
qualifier: 


e Use the CHAR_MAX macro as an indicator of a nonavailable value in the 
current locale only if the program is compiled without /UNSIGNED_CHAR 
(/NOUNSIGNED_CHAR is the default). 


e Ifthe program is compiled with /UNSIGNED_CHAR, use the SCHAR_MAX 
macro instead of the CHAR_MAX macro. 


In /NOUNSIGNED_CHAR mode, the values of CHAR MAX and SCHAR_ MAX 
are the same; therefore, comparison with SCHAR_MAX gives correct results 
regardless of the /[NO]JUNSIGNED_CHAR mode used. 


The members grouping and mon_grouping point to a string that defines the 

size of each group of digits when formatting a number. Each group size is 
separated by a semicolon (;). For example, if grouping points to the string 5;3 
and the thousands_sep character is a comma (,), the number 123450000 would be 
formatted as 1,234,50000. 


The elements of grouping and mon_grouping are interpreted as follows: 
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localeconv 


Value Interpretation 

CHAR_MAX No further grouping is performed. 

0 The previous element is to be used repeatedly for the remainder 
of the digits. 

other The integer value is the number of digits that comprise the 


current group. The next element is examined to determine the 
size of the next group of digits before the current group. 


The values of p_sign_posn and n_sign_posn are interpreted as follows: 


Value Interpretation 

0 Parentheses surround the number and currency symbol. 

1 The sign string precedes the number and currency symbol. 

2 The sign string succeeds the number and currency symbol. 

3 The sign string immediately precedes the number and currency 
symbol. 

4 The sign string immediately succeeds the number and currency 
symbol. 

Return Value 
x Pointer to the lconv structure. 


Example 


#include <stdlib.h> 
#include <stdio.h> 
#include <limits.h> 
#include <locale.h> 
#include <string.h> 


/* The following test program will set up the British English */ 
/* locale, and then extract the International Currency symbol  */ 


/* and the International Fractional Digits fields for this */ 
/* locale and print them. */ 
int main() 
{ 

/* Declare variables */ 


char *return_val; 
struct lconv *lconv_ptr; 


/* Load a locale */ 
return _val = (char *) setlocale(LC_ALL, "en GB.iso8859-1") ; 
/* Did the locale load successfully? */ 


if (return_val == NULL) { 


/* It failed to load the locale */ 
printf ("ERROR : The locale is unknown") ; 
exit (EXIT_FAILURE) ; 


/* Get the lconv structure from the locale */ 


lconv_ptr = (struct lconv *) localeconv() ; 
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/* Compare the international currency symbol string with an */ 
/* empty string. If they are equal, then the international */ 
/* currency symbol is not defined in the locale. */ 


if (strcmp (lconv_ptr->int_curr_symbol, "")) 
printf ("International Currency Symbol = %s\n", 
lconv_ptr->int_curr_symbol) ; 
} 
else { 
printf ("International Currency Symbol ="); 
printf ("[(Not available in this locale] \n"); 


/* Compare International Fractional Digits with CHAR MAX. x / 
/* If they are equal, then International Fractional Digits */ 
/* are not defined in this locale. */ 


if ((unsigned char) (lconv_ptr->int_frac digits) != CHAR MAX) { 
printf ("International Fractional Digits = %d\n", 
lconv_ptr->int_frac_ digits) ; 


} 

else { 
printf ("International Fractional Digits ="); 
printf ("[Not available in this locale] \n"); 


} 
Running the example program produces the following result: 


International Currency Symbol = GBP 
International Fractional Digits = 2 
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localtime, localtime_r 


Format 


Convert a time value to broken-down local time. 


#include <time.h> 
struct tm *localtime (const time_t *timer); 


struct tm “localtime_r (const time_t “timer, struct tm *result); so POSIX-1) 


Function Variants 


Arguments 


Description 
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Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the localtime_r function 
that is equivalent to the behavior before OpenVMS Version 7.0. 


timer 
A pointer to a time in seconds since the Epoch. You can generate this time by 
using the time function or you can supply a time. 


result 
A pointer to a tm structure where the result is stored. The tm structure is defined 
in the <time.h> header file, and is also shown in Table REF—4. 


The localtime and localtime_r functions convert the time (in seconds since the 
Epoch) pointed to by timer into a broken-down time, expressed as a local time, 
and store it in a tm structure. 


The difference between the localtime _r and localtime functions is that the 
former stores the result into a user-specified tm structure. The latter stores the 
result into thread-specific static memory allocated by the HP C RTL, and which is 
overwritten by subsequent calls to localtime; you must make a copy if you want 
to save it. 


On success, localtime returns a pointer to the tm structure; localtime r returns 
its second argument. On failure, these functions return the NULL pointer. 


The tm structure is defined in the <time.h> header file and described in 
Table REF—4. 


Table REF—4 tm Structure 


int tm_sec; Seconds after the minute (0-60) 
int tm_min; Minutes after the hour (0-59) 
int tm_hour; Hours since midnight (0-23) 
int tm_mday; Day of the month (1-31) 

int tm_mon; Months since January (1-11) 


(continued on next page) 


localtime, localtime_r 


Table REF-—4 (Cont.) tm Structure 


int tm_year; 
int tm_wday; 
int tm_yday; 
int tm_isdst; 


long tm_gmtof£;! 


char *tm_zone;! 


Years since 1900 

Days since Sunday (0-6) 

Days since January 1 (0-365) 
Daylight Savings Time flag 

e tm_isdst = 0 for Standard Time 
e tm_isdst = 1 for Daylight Time 


Seconds east of Greenwich (negative values indicate 
seconds west of Greenwich) 


Time zone string, for example "GMT" 


1This field is an extention to the ANSI C structure. It is present unless you compile your program 
with /STANDARD=ANSI89 or with _DECC_V4_SOURCE defined. 


The type time_t is defined in the <time.h> header file as follows: 


typedef long int time_t 


Note 


Generally speaking, UTC-based time functions can affect in-memory time- 
zone information, which is processwide data. However, if the system time 
zone remains the same during the execution of the application (which is 
the common case) and the cache of timezone files is enabled (which is the 
default), then the _r variant of the time functions asctime_r, ctime_r, 
gmtime_r and localtime_r, is both thread-safe and AST-reentrant. 


If, however, the system time zone can change during the execution of 

the application or the cache of timezone files is not enabled, then both 
variants of the UTC-based time functions belong to the third class of 

functions, which are neither thread-safe nor AST-reentrant. 


Return Values 


NULL 


Pointer to a tm structure. 
Indicates failure. 


REF-373 


log, log2, log10 


log, log2, log10 


Format 


Argument 


Description 


Return the logarithm of their arguments. 


#include <math.h> 

double log (double x); 

float logf (float x); (Aipha, 164) 

long double log! (long double x); (Alpha, 164) 
double log2 (double x); (Alpha, 164) 

float log2f (float x); (Alpha, 164) 

long double log2! (long double x); (Aipha, 164) 
double logi0 (double x); 

float log10f (float x); (Alpha, 164) 


long double log10! (long double x); (Alpha, 164) 


4 
A real number. 


The log functions compute the natural (base e) logarithm of x. 
The log2 functions compute the base 2 logarithm of x. 


The logi0 functions compute the common (base 10) logarithm of x. 


Return Values 
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x The logarithm of the argument (in the 
appropriate base). 

—HUGE_VAL x is 0 (errno is set to ERANGE), or x is negative 
(errno is set to EDOM). 

NaN x is NaN; errno is set to EDOM. 


log1p (ipha, 164) 


lOQ1P carpna, 164 


Computes In(1+y) accurately. 


Format 

#include <math.h> 

double logip (double y); 

float logipf (float y); 

long double logip! (long double y); 
Argument 

A real number greater than —1. 
Description 


The logip functions compute In(1+y) accurately, even for tiny y. 


Return Values 


x The natural logarithm of (1+y). 

—HUGE_VAL y is less than —1 (errno is set to EDOM), or y = 
—1 (errno is set to ERANGE). 

NaN y is NaN; errno is set to EDOM. 
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logb (aipra, 164 


Returns the radix-independent exponent of the argument. 


Format 

#include <math.h> 

double logb (double x); 

float logbf (float x); 

long double logbl (long double x); 
Argument 

x 

A nonzero, real number. 
Description 


The logb functions return the exponent of x, which is the integral part of 
logg |x |, as a signed floating-point value, for nonzero x. 


Return Values 


x The exponent of x. 
—HUGE_VAL x = 0.0; errno is set to EDOM. 
+Infinity x is +Infinity or —Infinity. 

NaN y is NaN; errno is set to EDOM. 
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longjmp 


Format 


Arguments 


Description 


Provides a way to transfer control from a nested series of function invocations 
back to a predefined point without returning normally; that is, by not using a 
series of return statements. The longjmp function restores the context of the 
environment buffer. 


#include <setjmp.h> 


void longimp (jmp_buf env, int value); 


env 

The environment buffer, which must be an array of integers long enough to hold 
the register context of the calling function. The type jmp_buf is defined in the 
<setjmp.h> header file. The contents of the general-purpose registers, including 
the program counter (PC), are stored in the buffer. 


value 
Passed from longjmp to setjmp, and then becomes the subsequent return value of 
the setjmp call. If value is passed as 0, it is converted to 1. 


When setjmp is first called, it returns the value 0. If longjmp is then called, 
naming the same environment as the call to setjmp, control is returned to the 
setjmp call as if it had returned normally a second time. The return value of 
setjmp in this second return is the valwe you supply in the longjmp call. To 
preserve the true value of setjmp, the function calling setjmp must not be called 
again until the associated longjmp is called. 


The setjmp function preserves the hardware general-purpose registers, and the 
longjmp function restores them. After a longjmp, all variables have their values 
as of the time of the longjmp except for local automatic variables not marked 
volatile. These variables have indeterminate values. 


The setjmp and longjmp functions rely on the OpenVMS condition-handling 
facility to effect a nonlocal goto with a signal handler. The longjmp function 

is implemented by generating a HP C RTL specified signal and allowing the 
OpenVMS condition-handling facility to unwind back to the desired destination. 
The HP C RTL must be in control of signal handling for any HP C image. 


For HP C to be in control of signal handling, you must establish all exception 
handlers through a call to the VAXCSESTABLISH function (rather than 
LIBSESTABLISH). See Section 4.2.5 and the VAXCSESTABLISH function for more 
information. 


Note 


The C RTL provides nonstandard decc$setjmp and decc$fast_longjmp 
functions for Alpha and 164 systems. To use these nonstandard functions 
instead of the standard ones, a program must be compiled with the 
__FAST SETJMP or __UNIX_SETJMP macros defined. 
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Restrictions 
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Unlike the standard longjmp function, the decc$fast_longjmp function 
does not convert its second argument from 0 to 1. After a call to 
decc$fast_longjmp, a corresponding setjmp function returns with the 
exact value of the second argument specified in the decc$fast_longjmp 
call. 


You cannot invoke the longjmp function from an OpenVMS condition handler. 
However, you may invoke longjmp from a signal handler that has been 
established for any signal supported by the HP C RTL, subject to the following 
nesting restrictions: 


The longjmp function will not work if invoked from nested signal handlers. 
The result of the longjmp function, when invoked from a signal handler that 
has been entered as a result of an exception generated in another signal 
handler, is undefined. 


Do not invoke the setjmp function from a signal handler unless the associated 
longjmp is to be issued before the handling of that signal is completed. 


Do not invoke the longjmp function from within an exit handler (established 
with atexit or SYS$DCLEXH). Exit handlers are invoked after image 
tear-down, so the destination address of the longjmp no longer exists. 


Invoking longjmp from within a signal handler to return to the main thread 
of execution might leave your program in an inconsistent state. Possible 
side effects include the inability to perform I/O or to receive any more UNIX 
signals. 


longname 


longname 


Format 


Returns the full name of the terminal. 


#include <curses.h> 


void longname (char *termbuf, char *name); 


Function Variants 


Arguments 


Description 


The longname function has variants named longname32 and _longnameé4 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


termbuf 
A string containing the name of the terminal. 


name 
A character-string buffer with a minimum length of 64 characters. 


The terminal name is in a readable format so that you can double-check to be 
sure that Curses has correctly identified your terminal. The dummy argument 
termbuf is required for UNIX software compatibility and serves no function in 
the OpenVMS environment. If portability is a concern, you must write a set of 
dummy routines to perform the functionality provided by the database termcap in 
the UNIX system environment. 


REF-379 


lrand48 


lrand48 


Format 


Description 


Generates uniformly distributed pseudorandom-number sequences. Returns 
48-bit signed long integers. 


#include <stdlib.h> 
long int Irand48 (void); 


The lrand48 function generates pseudorandom numbers using the linear 
congruential algorithm and 48-bit integer arithmetic. 


It returns nonnegative, long integers uniformly distributed over the range of y 
values such that 0 < y < 221. 


Before you call the lrand48 function use either srand48, seed48, or lcong48 to 
initialize the random-number generator. You must initialize prior to invoking the 
lrand48 function, because it stores the last 48-bit Xi generated into an internal 
buffer. (Although it is not recommended, constant default initializer values are 
supplied automatically if the drand48, lrand48, or mrand48 functions are called 
without first calling an initialization function.) 


The function works by generating a sequence of 48-bit integer values, Xi, 
according to the linear congruential formula: 


Xn+1 = (aXn+c)mod m n >= 0 


The argument m equals 2*°, so 48-bit integer arithmetic is performed. Unless you 
invoke the 1cong48 function, the multiplier value a and the addend value c are: 


5DEECE66D16 = 273673163155 
B16 = 138 


¢ 


The value returned by the lrand48 function is computed by first generating the 
next 48-bit Xi in the sequence. Then the appropriate bits, according to the type of 
data item to be returned, are copied from the high-order (most significant) bits of 
Xi and transformed into the returned value. 


See also drand48, lcong48, mrand48, seed48, and srand48. 


Return Value 
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n Signed nonnegative long integers uniformly 
distributed over the range 0 < y < 2°. 


Irint (ipra, 164 


Irint (ipra, 164) 


Rounds to the nearest integer value, rounding according to the current rounding 
direction. 
Format 
#include <math.h> 
long Irint (double x); 
long Irintf (float x); 


long Irintl (long double x): 


Argument 


x 
A real value. 


Description 


The lrint functions return the rounded integer value of x, rounded according to 
the current rounding direction. 


Return Values 


n Upon success, the rounded integer value. 
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lround (ipha, 164) 


IrOUNA (pra, 164) 


Rounds to the nearest integer value, rounding halfway cases away from zero 
regardless of the current rounding direction. 


Format 

#include <math.h> 

long Iround (double x); 

long Iroundf (float x); 

long Iround! (long double x); 
Argument 

x 

A real value. 
Description 


The lround functions return the rounded integer value of x, with halfway cases 
rounded away from zero regardless of the current rounding direction. 


Return Values 


n Upon success, the rounded integer value. 
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Iseek 


Format 


Arguments 


Description 


Positions a file to an arbitrary byte position and returns the new position. 


#include <unistd.h> 


off_t Iseek (int file_desc, off_t offset, int direction); 


file_desc 
An integer returned by open, creat, dup, or dup2. 


offset 

The offset, specified in bytes. The off_t data type is either a 32-bit or a 64-bit 
integer. The 64-bit interface allows for file sizes greater than 2 GB, and can 
be selected at compile time by defining the LLARGEFILE feature-test macro as 
follows: 


CC/DEFINE= LARGEFILE 


direction 

An integer indicating whether the offset is to be measured forward from the 
beginning of the file (direction=SEEK_SET), forward from the current position 
(direction=SEEK_CUR), or backward from the end of the file (direction=SEEK_ 
END). 


The lseek function can position a fixed-length record-access file with no carriage 
control or a stream-access file on any byte offset, but can position all other files 
only on record boundaries. 


The available Standard I/O functions position a record file at its first byte, at 
the end-of-file, or on a record boundary. Therefore, the arguments given to lseek 
must specify either the beginning or end of the file, a 0 offset from the current 
position (an arbitrary record boundary), or the position returned by a previous, 
valid lseek call. 


This function returns the new file position as an integer of type off _t which, like 
the offset argument, is either a 64-bit integer if LLARGEFILE is defined, or a 
32-bit integer if not. 


For a portable way to position an arbitrary byte location with any type of file, see 
the fgetpos and fsetpos functions. 


Caution 


If, while accessing a stream file, you seek beyond the end-of-file and then 
write to the file, the 1seek function creates a hole by filling the skipped 
bytes with zeros. 


In general, for record files, lseek should only be directed to an absolute 
position that was returned by a previous valid call to 1seek or to the 
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beginning or end of a file. If a call to 1seek does not satisfy these 
conditions, the results are unpredictable. 


See also open, creat, dup, dup2, and fseek. 


Return Values 


x The new file position. 


-1 Indicates that the file descriptor is undefined, or 
a seek was attempted before the beginning of the 
file. 
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Istat (aipna, 164 


Retrieves information about the specified file. 


Format 

#include <sys/stat.h> 

int Istat (const char “restrict file_path, struct stat “restrict user_buffer); 
Arguments 

file_path 

The name of the file for which you want to retrieve information. 

user_buffer 

The stat structure in which information is returned. 
Description 


The lstat function retrieves information about the specified file (file_path). If the 
file is a symbolic link, information about the link itself is returned (in contrast to 
stat, which returns information about the file that the symbolic link points to). 


See also symlink, unlink, readlink, realpath, and lchown. 
Return Values 


0 Successful completion. 


-1 Indicates an error. errno is set to any errno 
value returned by stat. 
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lwait 

Waits for I/O on a specific file to complete. 
Format 

#include <stdio.h> 

int Iwait (int fa); 
Argument 

fd 


A file descriptor corresponding to an open file. 


Description 


The lwait function is used primarily to wait for completion of pending 
asynchronous I/O. 


Return Values 


0 Indicates successful completion. 
—1 Indicates an error. 
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malloc 


Allocates an area of memory. These functions are AST-reentrant. 


Format 
#include <stdlib.h> 


void *malloc (size_t size); 


Function Variants 


The malloc function has variants named malloc32 and mallocé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Argument 


size 
The total number of bytes to be allocated. 


Description 


The malloc function allocates a contiguous area of memory whose size, in bytes, 
is supplied as an argument. The space is not initialized. 


Note 


The malloc routines call the system routine LIB$VM_MALLOC. Because 
LIB$VM_MALLOC is designed as a general-purpose routine to allocate 
memory, it is called upon in a wide array of scenarios to allocate and 
reallocate blocks efficiently. The most common usage is the management 
of smaller blocks of memory, and the most important aspect of memory 
allocation under these circumstances is efficiency. 


LIB$VM_MALLOC makes use of its own free space to satisfy requests, 
once the heap storage is consumed by splitting large blocks and merging 
adjacent blocks. Memory can still become fragmented, leaving unused 
blocks. Once heap storage is consumed, LIB$VM_MALLOC manages its 
own free space and merged blocks to satisfy requests, but varying sizes of 
memory allocations can cause blocks to be left unused. 


Because LIB$VM_MALLOC cannot be made to satisfy all situations in 
the best possible manner, perform your own memory management if you 
have special memory usage needs. This assures the best use of memory 
for your particular application. 


The OpenVMS Programming Concepts Manual explains the several 
memory allocation routines that are available. They are grouped into 
three levels of hierarchy: 


1. At the highest level are the RTL Heap Management Routines 
LIB$GET_VM and LIB$FREE_VM, which provide a mechanism 
for allocating and freeing blocks of memory of arbitrary size. Also 
at this level are the routines based on the concept of zones, such as 
LIB$CREATE_VM_ZONE, and so on. 
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2. At the next level are the RTL Page Management routines LIB$GET_ 
VM_PAGE and LIB$FREE_VM_PAGE, which allocate a specified 
number of contiguous pages. 


3. At the lowest level are the Memory Management System Services, 
such as $CRETVA and $EXPREG, that provide extensive control 
over address space allocation. At this level, you must manage the 
allocation precisely. 


Return Values 


x The address of the first byte, which is aligned on 
a quadword boundary (Alpha only) or an octaword 
boundary (164 only) . 

NULL Indicates that the function is unable to allocate 
enough memory. errno is set to ENOMEM. 


REF-388 


mblen 


mblen 


Format 


Arguments 


Description 


Determines the number of bytes comprising a multibyte character. 


#include <stdlib.h> 


int mblen (const char *s, size_t n); 


s 
A pointer to the multibyte character. 


n 
The maximum number of bytes that comprise the multibyte character. 


If the character is n bytes or less, the mblen function returns the number of bytes 
comprising the multibyte character pointed to by s. If the character is greater 
than n bytes, the function returns —1 to indicate an error. 


This function is affected by the LC_CTYPE category of the program’s current 
locale. 


Return Values 


x The number of bytes that comprise the multibyte 
character, if the next n or fewer bytes form a 
valid character. 

0 If s is NULL or a pointer to the NULL character. 

-1 Indicates an error. The function sets errno to 
EILSEQ — Invalid character detected. 
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mbrlien 


Format 


Arguments 


Description 


Determines the number of bytes comprising a multibyte character. 


#include <wchar.h> 


size_t mbrlen (const char *s, size_t n, mbstate_t *ps); 


s 
A pointer to a multibyte character. 


n 
The maximum number of bytes that comprise the multibyte character. 


ps 
A pointer to the mbstate_t object. If a NULL pointer is specified, the function 
uses its internal mbstate_t object. mbstate_t is an opaque datatype intended to 
keep the conversion state for the state-dependent codesets. 


The mbrlen function is equivalent to the call: 
mbrtowc(NULL, s, n, ps != NULL ? ps : &internal) 
Where internal is the mbstate_t object for the mbrlen function. 


If the multibyte character pointed to by s is of n bytes or less, the function returns 
the number of bytes comprising the character (including any shift sequences). 


If either an encoding error occurs or the next n bytes contribute to an incomplete 
but potentially valid multibyte character, the function returns —1 or —2, 
respectively. 


See also mbrtowc. 


Return Values 
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x The number of bytes comprising the multibyte 
character. 

0 Indicates that s is a NULL pointer or a pointer 
to a null byte. 

-1 Indicates an encoding error, in which case the 


next n or fewer bytes do not contribute to a 
complete and valid multibyte character. errno is 
set to EILSEQ; the conversion state is undefined. 


—2 Indicates an incomplete but potentially valid 
multibyte character (all n bytes have been 
processed). 
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mbrtowc 


Format 


Arguments 


Description 


Converts a multibyte character to its wide-character representation. 


#include <wchar.h> 


size_t mbrtowc (wchar_t *pwe, const char *s, size_t n, mbstate_t *ps); 


pwc 
A pointer to the resulting wide-character code. 


s 
A pointer to a multibyte character. 


n 
The maximum number of bytes that comprise the multibyte character. 


ps 
A pointer to the mbstate t object. If a NULL pointer is specified, the function 
uses its internal mbstate_ t object. mbstate t is an opaque datatype intended to 
keep the conversion state for the state-dependent codesets. 


If s is a NULL pointer, mbrtowc is equivalent to the call: 
mbrtowc (NULL, "", 1, ps) 
In this case, the values of pwc and n are ignored. 


If s is not a NULL pointer, mbrtowc inspects at most n bytes beginning with the 
byte pointed to by s to determine the number of bytes needed to complete the 
next multibyte character (including any shift sequences). 


If the function determines that the next multibyte character is completed, it 
determines the value of the corresponding wide character and then, if pwc is 
not a NULL pointer, stores that value in the object pointed to by pwc. If the 
corresponding wide character is the null wide character, the resulting state 
described is the initial conversion state. 


If mortowc is called as a counting function, which means that pwc is a NULL 
pointer and s is neither a NULL pointer nor a pointer to a null byte, the value of 
the internal mbstate_t object will remain unchanged. 


Return Values 


x The number of bytes comprising the multibyte 
character. 
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The next n or fewer bytes complete the multibyte 
character that corresponds to the null wide 
character (which is the value stored if pwc is 
not a NULL pointer). The wide-character code 
corresponding to a null byte is zero. 

Indicates an encoding error. The next n or fewer 
bytes do not contribute to a complete and valid 
multibyte character. errno is set to EILSEQ. The 
conversion state is undefined. 

Indicates an incomplete but potentially valid 
multibyte character (all n bytes have been 
processed). 
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mbstowcs 


Format 


Arguments 


Description 


Converts a sequence of multibyte characters into a sequence of corresponding 
wide-character codes. 


#include <stdlib.h> 


size_t mbstowcs (wchar_t “pwes, const char *s, size_t n); 


pwcs 
A pointer to the array containing the resulting sequence of wide-character codes. 


s 
A pointer to the array of multibyte characters. 


n 
The maximum number of wide-character codes that can be stored in the array 
pointed to by pwces. 


The mbstowcs function converts a sequence of multibyte characters from the 
array pointed to by s to a sequence of wide-character codes that are stored into 
the array pointed to by pwcs, up to a maximum of n codes. 


This function is affected by the LC_CTYPE category of the program’s current 
locale. If copying takes place between objects that overlap, the behavior is 
undefined. 


Return Values 


x The number of array elements modified or 
required, not included any terminating zero 
code. The array will not be zero-terminated if the 
value returned is n. If pwcs is the NULL pointer, 
mbstowcs returns the number of elements 
required for the wide-character array. 


(size t)—-1 Indicates that an error occurred. The function 
sets errno to EILSEQ - Invalid character 
detected. 
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mbtowc 


Format 


Arguments 


Description 


Converts a multibyte character to its wide-character equivalent. 


#include <stdlib.h> 


int mbtowc (wchar_t *pwe, const char *s, size_t n); 


pwc 
A pointer to the resulting wide-character code. 


s 
A pointer to the multibyte character. 


n 
The maximum number of bytes that comprise the next multibyte character. 


If the character is n or fewer bytes, the motowc function converts the multibyte 
character pointed to by s to its wide-character equivalent. If the character is 
invalid or greater than n bytes, the function returns —1 to indicate an error. 


If pwc is a NULL pointer and s is not a null pointer, the function determines 
the number of bytes that constitute the multibyte character pointed to by s 
(regardless of the value of 7). 


This function is affected by the LC_CTYPE category of the program’s current 
locale. 


Return Values 
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x The number of bytes that comprise the valid 
character pointed to by s. 

0 If s is either a NULL pointer or a pointer to the 
null byte. 

—1 Indicates an error. The function sets errno to 


EILSEQ — Invalid character detected. 


mbsinit 


mbsinit 
Determines whether an mbstate_t object decribes an initial conversion state. 
Format 
#include <wchar.h> 
int mbsinit (const mbstate_t “ps); 
Argument 
ps 
A pointer to the mbstate_t object. mbstate_t is an opaque datatype intended to 
keep the conversion state for the state-dependent codesets. 
Description 


If ps is not a NULL pointer, the mbsinit function determines whether the 
mbstate_t object pointed to by ps describes an initial conversion state. A zero 
mbstate_t object always describes an initial conversion state. 


Return Values 


nonzero The ps argument is a NULL pointer, or the 
mbstate_t object pointed to by ps describes an 
initial conversion state. 

0 The mbstate_t object pointed to by ps does not 
describe an initial conversion state. 
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mbsrtowcs 


Format 


Converts a sequence of multibyte characters to a sequence of corresponding 
wide-character codes. 


#include <wchar.h> 


size_t mbsrtowcs (wchar_t “dst, const char *“src, size_t len, mbstate_t *ps); 


Function Variants 


Arguments 


Description 
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The mbsrtowcs function has variants named _mbsrtowcs32 and _mbsrtowcs64 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


dst 
A pointer to the destination array containing the resulting sequence of wide- 
character codes. 


src 
An address of the pointer to an array containing a sequence of multibyte 
characters to be converted. 


len 
The maximum number of wide character codes that can be stored in the array 
pointed to by dst. 


ps 
A pointer to the mbstate_t object. If a NULL pointer is specified, the function 
uses its internal mbstate_t object. mbstate_t is an opaque datatype intended to 
keep the conversion state for the state-dependent codesets. 


The mbsrtowcs function converts a sequence of multibyte characters, beginning 
in the conversion state described by the object pointed to by ps, from the array 
indirectly pointed to by src, into a sequence of corresponding wide characters. 


If dst is not a NULL pointer, the converted characters are stored into the array 
pointed to by dst. Conversion continues up to and including a terminating null 
character, which is also stored. 


Conversion stops earlier for one of the following reasons: 


e A sequence of bytes is encountered that does not form a valid multibyte 
character. 


e If dst is not a NULL pointer, when Jen codes have been stored into the array 
pointed to by dst. 


mbsrtowcs 


If dst is not a NULL pointer, the pointer object pointed to by src is assigned either 
a NULL pointer (if the conversion stopped because of reaching a terminating null 
wide character), or the address just beyond the last multibyte character converted 
Gif any). If conversion stopped because of reaching a terminating null wide 
character, the resulting state described is the initial conversion state. 


Return Values 


n The number of multibyte characters successfully 
converted, sequence, not including the 
terminating null (if any). 


—1 Indicates an error. A sequence of bytes that 
do not form valid multibyte character was 
encountered. errno is set to EILSEQ; the 
conversion state is undefined. 
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memccpy 


Format 


Copies characters sequentially between strings in memory areas. 


#include <string.h> 


void “*memccpy (void “dest, void “source, int c, size_t n); 


Function Variants 


Arguments 


Description 


The memccpy function has variants named memccpy32 and memccpyé64 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


dest 
A pointer to the location of a destination string. 


source 
A pointer to the location of a source string. 


c 
A character that you want to search for. 


n 
The number of charcter you want to copy. 


The memccpy function operates on strings in memory areas. A memory area is a 
group of contiguous characters bound by a count and not terminated by a null 
character. The function does not check for overflow of the receiving memory area. 
The memccpy function is defined in the <string.h> header file. 


The memccpy function sequentially copies characters from the location pointed to 
by source into the location pointed to by dest until one of the following occurs: 


e The character specified by c (converted to an unsigned char) is copied. 


e The number of characters specified by n is copied. 


Return Values 
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x A pointer to the character following the character 
specified by c in the string pointed to by dest. 

NULL Indicates an error. The character c is not found 
after scanning n characters in the string. 
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memchr 


Format 


Locates the first occurrence of the specified byte within the initial size bytes of a 
given object. 


#include <string.h> 


void *memchr (const void *s7, int c, size_t size); 


Function Variants 


Arguments 


Description 


The memchr function has variants named _memchr32 and _memchré4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


s1 
A pointer to the object to be searched. 


c 
The byte value to be located. 


size 
The length of the object to be searched. 


If size is zero, memchr returns NULL. 


Unlike strchr, the memchr function does not stop when it encounters a null 
character. 


Return Values 


pointer A pointer to the first occurrence of the byte. 
NULL Indicates that the specified byte does not occur in 
the object. 
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memcmp 


Format 


Arguments 


Description 


Compares two objects, byte by byte. The compare operation starts with the first 
byte in each object. 


#include <string.h> 


int memcmp (const void *s1, const void *s2, size_t size); 


s1 
A pointer to the first object. 


s2 
A pointer to the second object. 


size 
The length of the objects to be compared. 


If size is zero, the two objects are considered equal. 


The memcmp function uses native byte comparison. The sign of the value returned 
is determined by the sign of the difference between the values of the first pair 
of unlike bytes in the objects being compared. Unlike the strcmp function, the 
memcmp function does not stop when a null character is encountered. 


Return Value 


REF—400 


x An integer less than, equal to, or greater than 
0, depending on whether the lexical value of the 
first object is less than, equal to, or greater than 
that of the second object. 
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memcpy 


Format 


Copies a specified number of bytes from one object to another. 


#include <string.h> 


void “memcpy (void *dest, const void *source, size_t size); 


Function Variants 


Arguments 


Description 


The memcpy function has variants named _memcpy32 and memcpyé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


dest 
A pointer to the destination object. 


source 
A pointer to the source object. 


size 
The length of the object to be copied. 


The memcpy function copies size bytes from the object pointed to by source to 
the object pointed to by dest; it does not check for the overflow of the receiving 
memory area (dest). Unlike the strcpy function, the memcpy function does not 
stop when a null character is encountered. 


Return Value 


x The value of dest. 
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memmove 


Format 


Copies a specified number of bytes from one object to another. 


#include <string.h> 


void *memmove (void “dest, const void “source, size_t size); 


Function Variants 


Arguments 


Description 


The memmove function has variants named _memmove32 and memmoveé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


dest 
A pointer to the destination object. 


source 
A pointer to the source object. 


size 
The length of the object to be copied. 


In HP C for OpenVMS Systems, memmove and memcpy perform the same function. 
Programs that require portability should use memmove if the area pointed at by 
dest could overlap the area pointed at by source. 


Return Value 


Example 
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x The value of dest. 


#include <string.h> 
#include <stdio.h> 


main() 
char pdest [14] = "hello there"; 
char *psource = "you are there"; 


memmove (pdest, psource, 7); 
printf ("%s\n", pdest) ; 


} 


This example produces the following output: 


you are there 


memset 


memset 


Format 


Sets a specified number of bytes in a given object to a given value. 


#include <string.h> 


void *memset (void *s, int value, size_t size); 


Function Variants 


Arguments 


Description 


The memset function has variants named memset32 and memseté4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


s 
An array pointer. 


value 
The value to be placed in s. 


size 
The number of bytes to be placed in s. 


The memset function copies value (converted to an unsigned char) into each of the 
first size characters of the object pointed to by s. 


This function returns s. It does not check for the overflow of the receiving 
memory area pointed to by s. 


Return Value 


x The value of s. 
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mkdir 


Format 


Arguments 
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Creates a directory. 


#include <stat.h> 
int mkdir (const char *dir_spec, mode_t mode); (iso POSIX-1) 


int mkdir (const char *dir_spec, mode_t mode, ... ); (HP C Extension) 


dir_spec 
A valid OpenVMS or UNIX style directory specification that may contain a device 
name. For example: 


DBAO: [BAY.WINDOWS] /* OpenVMS */ 
/dba0/bay/windows /* UNIX style */ 


This specification cannot contain a node name, file name, file extension, file 
version, or a wildcard character. The same restriction applies to the UNIX style 
directory specifications. For more information about the restrictions on UNIX 
style specifications, see Chapter 1. 


mode 
A file protection. See the chmod function in this section for information about the 
specific file protections. 


The file protection of the new directory is derived from the mode argument, the 
process’s file protection mask (see the umask function), and the parent-directory 
default protections. 


In a manner consistent with the OpenVMS behavior for creating directories, 
mkdir never applies delete access to the directory. An application that needs to 
set delete access should use an explicit call to chmod to set write permission. 


See the Description section of this function for more information about how the 
file protection is set for the newly created directory. 


Represents the following optional arguments. These arguments have fixed 
position in the argument list, and cannot be arbitrarily placed. 


unsigned int uic 

The user identification code (UIC) that identifies the owner of the created 
directory. If this argument is 0, the HP C RTL gives the created directory the 
UIC of the parent directory. If this argument is not specified, the HP C RTL 
gives the created directory your UIC. This optional argument is specific to the 
HP C RTL and is not portable. 


unsigned short max_versions 

The maximum number of file versions to be retained in the created directory. 
The system automatically purges the directory keeping, at most, max_versions 
number of every file. 


If this argument is 0, the HP C RTL does not place a limit on the maximum 
number of file versions. 


Description 


mkdir 


If this argument is not specified, the HP C RTL gives the created directory 
the default version limit of the parent directory. 


This optional argument is specific to the HP C RTL and is not portable. 


unsigned short r_v_number 

The volume (device) on which to place the created directory if the device 

is part of a volume set. If this argument is not specified, the HP C RTL 
arbitrarily places the created directory within the volume set. This optional 
argument is specific to the HP C RTL and is not portable. 


If dir_spec specifies a path that includes directories, which do not exist, 
intermediate directories are also created. This differs from the behavior of 

the UNIX system where these intermediate directories must exist and will not be 
created. 


If you do not specify any optional arguments, the HP C RTL gives the directory 
your UIC and the default version limit of the parent directory, and arbitrarily 

places the directory within the volume set. You cannot get the default behavior 
for the uic or max_versions arguments if you specify any arguments after them. 


Note 


The way to create files with OpenVMS RMS default protections using 
the UNIX system-call functions umask, mkdir, creat, and open is to 
call mkdir, creat, and open with a file-protection mode argument of 
0777 in a program that never specifically calls umask. These default 
protections include correctly establishing protections based on ACLs, 
previous versions of files, and so on. 


In programs that do vfork/exec calls, the new process image inherits 
whether umask has ever been called or not from the calling process image. 
The umask setting and whether the umask function has ever been called 
are both inherited attributes. 


The file protection supplied by the mode argument is modified by the process’s 
file protection mask in such a way that the file protection for the new directory 
is set to the bitwise AND of the mode argument and the complement of the file 
protection mask. 


Default file protections are supplied to the new directory from the parent- 
directory such that if a protection value bit in the new directory is zero, then 
the value of this bit is inherited from the parent directory. However, bits in 
the parent directory’s file protection that indicate delete access do not cause 
corresponding bits to be set in the new directory’s file protection. 


Return Values 


0 Indicates success. 
-1 Indicates failure. 
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Examples 


umask (0002); /* turn world write access off */ 
mkdir ("sys$disk:[.parentdir.childdir]", 0222); /* turn write 
access on */ 


Parent directory file protection: System:RWD, Owner:RWD, Group:R, 
World:R 


The file protection derived from the combination of the mode argument 
and the file protection mask set by umask is (0222) & ~(0002), which is 
0220. When the parent directory defaults are applied to this protection, the 
protection for the new directory becomes: 


File protection: System:RWD, Owner:RWD, Group:RWD, World:R 


umask (0000); 
mkdir ("sys$disk:[.parentdir.childdir]", 0444); /* turn read 
access on */ 


Parent directory file protection: System:RWD, Owner:RWD, 
Group:RWD, World:RWD 


The file protection derived from the combination of the mode argument 
and the file protection mask set by umask is (0444) & ~(0000), which is 
0444. When the parent directory defaults are applied to this protection, the 
protection for the new directory is: 


File protection: System:RW, Owner:RW, Group:RW, World:RW 


Note that delete access is not inherited. 
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mkstemp 


Format 


Argument 


Description 


Constructs a unique file name. 


#include <stdlib.h> 


int mkstemp (char *template); 


template 
A pointer to a string that is replaced with a unique file name. The string in the 
template argument must be a file name with six trailing Xs. 


The mkstemp function replaces the six trailing Xs of the string pointed to by 
template with a unique set of characters, and returns a file descriptor for the file 
open for reading and writing. 


The string pointed to by template should look like a file name with six trailing 
X’s. The mkstemp function replaces each X with a character from the portable 
filename character set, making sure not to duplicate an existing file name. 


If the string pointed to by template does not contain six trailing Xs, —1 is 
returned. 


Return Values 


x An open file descriptor. 


—1 Indicates an error. (The string pointed to by 
template does not contain six trailing Xs.) 
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mktemp 


Creates a unique file name from a template. 


Format 
#include <stdlib.h> 


char *mktemp (char *template): 


Function Variants 


The mktemp function has variants named _mktemp32 and _mktempé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Argument 
template 
A pointer to a buffer containing a user-defined template. You supply the template 
in the form, namXXXXXX. The six trailing Xs are replaced by a unique series 
of characters. You may supply the first three characters. Because the template 
argument is overwritten, do not specify a string literal (const object). 
Description 


The use of mktemp is not recommended for new applications. See the tmpnam and 
mkstemp functions for the preferable alternatives. 


Return Value 
x A pointer to the template, with the template 
modified to contain the created file name. If this 


value is a pointer to a null string, it indicates 
that a unique file name cannot be created. 
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mktime 


Format 


Converts a local-time structure to a time, in seconds, since the Epoch. 


#include <time.h> 


time_t mktime (struct tm *timeptr); 


Function Variants 


Argument 


Description 


Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the mkt ime function that 
is equivalent to the behavior before OpenVMS Version 7.0. 


timeptr 
A pointer to the local-time structure. 


The mktime function converts a local-time structure (struct tm) pointed to by 
timeptr, to a time in seconds since the Epoch (a time_t variable), in the same 
manner as the values returned by the time function. 


The original values of the tm_wday and tm_yday components of the structure 

are ignored, and the original values of the other components are not restricted 

to the ranges defined in <time.h>. Upon successful completion, the tm_wday 

and tm_yday components of the structure are set appropriately, and the other 
components are set to represent the specified time, with their values forced to the 
normal range. 


If the local time cannot be encoded, then mktime returns the value (time_t)(—1). 
The time_t type is defined in the <time.h> header file as follows: 

typedef unsigned long int time _t; 

Local time-zone information is set as if mktime called tzset. 


If the tm_isdst field in the local-time structure pointed to by timeptr is positive, 
mktime initially presumes that Daylight Savings Time (DST) is in effect for the 
specified time. 


If tm_isdst is 0, mktime initially presumes that DST is not in effect. 


If tm_isdst is negative, mktime attempts to determine whether or not DST is in 
effect for the specified time. 


Return Values 


x The specified calendar time encoded as a value of 
type time t. 
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(time_t)(—1) If the local time cannot be encoded. 


Be aware that a return value of (time _t)(—1) can 
also represent the valid date: Sun Feb 7 06:28:15 
2106. 
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mmap 


Format 


Maps file system object into virtual memory. This function is reentrant. 


#include <types.h> 
#include + <mman.h> 
void mmap (void “addr, size_t /en, int prot, int flags, int filedes, off_t off); X/Open, POSIX-1) 


void mmap (void “addr, size_t /en, int prot, int flags, int filedes, off_t off ...); GP C Extension) 


Function Variants 


Arguments 


The mmap function has variants named _mmap32 and _mmap64 for use with 32-bit 
and 64-bit pointer sizes, respectively. See Section 1.10 for more information on 
using pointer-size-specific functions. 


addr 
The starting address of the new region (truncated to a page boundary). 


len 
The length, in bytes, of the new region (rounded up to a page boundary). 


prot 
Access permission, as defined in the <mman.h> header file. Specify either PROT_ 
NONE, PROT_READ, or PROT_WRITE. 


flags 

Attributes of the mapped region as the results of a bitwise-inclusive OR operation 
on any combination of the following: 

e MAP_FILE or MAP_ANONYMOUS 

e MAP_VARIABLE or MAP_FIXED 


e MAP SHARED or MAP_PRIVATE 


filedes 
The file that you want to map to the new mapped file region returned by the open 
function. 


off 

The offset, specified in bytes. The off _t data type is either a 64-bit or 32-bit 
integer. The 64-bit interface allows for file sizes greater than 2 GB, and can 
be selected at compile time by defining the LLARGEFILE feature-test macro as 
follows: 


CC/DEFINE= LARGEFILE 


An optional integer specifying additional flags for the SYS$CRMPSC system 
service for MAP_SHARED. This optional argument (HP C Extension) of the mmap 
function was introduced in OpenVMS Version 7.2. 
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Description 
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The mmap function creates a new mapped file region, a new private region, or a 
new shared memory region. 


Your application must ensure correct synchronization when using mmap in 
conjunction with any other file access method, such as read and write, and 
standard input/output. 


Before calling mmap, the calling application must also ensure that all bytes in the 
range loff, off+len] are written to the file (using the fsync function, for example). 
If this requirement is not met, mmap fails with errno set to ENXIO (No such 
device or address). 


The addr and len arguments specify the requested starting address and length, 
in bytes, for the new region. The address is a multiple of the page size returned 
by sysconf(_SC_ PAGE SIZE). 


If the Jen argument is not a multiple of the page size returned by 

sysconf (_SC_PAGE SIZE), then the result of any reference to an address between 
the end of the region and the end of the page containing the end of the region is 
undefined. 


The flags argument specifies attributes of the mapped region. Values for flags are 
constructed by a bitwise-inclusive OR operation on the flags from the following 
list of symbolic names defined in the <mman.h> header file: 


MAP_FILE Create a mapped file region. 
MAP_ANONYMOUS Create an unnamed memory region. 
MAP_VARIABLE Place region at the computed address. 
MAP_FIXED Place region at fixed address. 
MAP_SHARED Share changes. 

MAP_PRIVATE Changes are private. 


The MAP_FILE and MAP_ANONYMOUS flags control whether the region you 
want to map is a mapped file region or an anonymous shared memory region. 
One of these flags must be selected. 


If MAP_FILE is set in the flags argument: 


e Anew mapped file region is created, mapping the file associated with the 
filedes argument. 


e The off argument specifies the file byte offset where the mapping 
starts. This offset must be a multiple of the page size returned by 
sysconf (_SC_PAGE SIZE). 


e Ifthe end of the mapped file region is beyond the end of the file, the result 
of any reference to an address in the mapped file region corresponding to an 
offset beyond the end of the file is unspecified. 


If MAP_ANONYMOUS is set in the flags argument: 
e Anew memory region is created and initialized to all zeros. 


e If the filedes argument is not —1, the mmap function fails. 


mmap 


The new region is placed at the requested address if the requested address is not 
null and it is possible to place the region at this address. When the requested 
address is null or the region cannot be placed at the requested address, the 
MAP_VARIABLE and MAP_FIXED flags control the placement of the region. One 
of these flags must be selected. 


If MAP_VARIABLE is set in the flags argument: 


e If the requested address is null or if it is not possible for the system to 
place the region at the requested address, the region is placed at an address 
selected by the system. 


If MAP_FIXED is set in the flags argument: 


e Ifthe requested address is not null, the mmap function succeeds even if the 
requested address is already part of another region. (If the address is within 
an existing region, the effect on the pages within that region and within the 
area of the overlap produced by the two regions is the same as if they were 
unmapped. In other words, whatever is mapped between addr and addr + len 
is unmapped.) 


e Ifthe requested address is null and MAP_FIXED is specified, the results are 
undefined. 


The MAP_PRIVATE and MAP_SHARED flags control the visibility of 
modifications to the mapped file or shared memory region. One of these flags 
must be selected. 


If MAP_SHARED is set in the flags argument: 


e Ifthe region is a mapped region, modifications to the region are visible to 
other processes that mapped the same region using MAP_SHARED. 


e Ifthe region is a mapped file region, modifications to the region are written to 
the file. (Note that the modifications are not immediately written to the file 
because of buffer cache delay; that is, the write to the file does not occur until 
there is a need to reuse the buffer cache. If the modifications must be written 
to the file immediately, use the msync function to ensure that this is done.) 


If MAP_PRIVATE is set in the flags argument: 


e Modifications to the mapped region by the calling process are not visible to 
other processes that mapped the same region using either MAP_PRIVATE or 
MAP_SHARED. 


e Modifications to the mapped region by the calling process are not written to 
the file. 


It is unspecified whether modifications by processes that mapped the region using 
MAP_SHARED are visible to other processes that mapped the same region using 
MAP_PRIVATE. 


The prot argument specifies access permissions for the mapped region. Specify 
one of the following: 


PROT_NONE No access 
PROT_READ Read-only 
PROT_WRITE Read/Write access 
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After the successful completion of the mmap function, you can close the filedes 
argument without effect on the mapped region or on the contents of the 
mapped file. Each mapped region creates a file reference, similar to an open 
file descriptor, that prevents the file data from being deallocated. 


Note 


The following rules apply to OpenVMS specific file references: 


e Because of the additional file reference, if filedes is not opened for file 
sharing, mmap reopens it with file sharing enabled. 


e The additional file reference that remains for mapped regions implies 
that a later open, fopen, or create call to the file that is mapped must 
specify file sharing. 


Modifications made to the file using the write function are visible to mapped 
regions, and modifications to a mapped region are visible with the read function. 


Note 


Beginning with OpenVMS Version 7.2, while processing a MAP_ 
SHARED request, the mmap function constructs the flags argument of 
the SYS$CRMPSC service as a bitwise inclusive OR of those bits it sets 
by itself to fulfill the MAP SHARED request and those bits specified by 
the caller in the optional argument. 


By default, for MAP_SHARED the mmap function creates a temporary 
group global section. The optional mmap argument provides the caller with 
direct access to the features of the SYS$CRMPSC system service. 


Using the optional argument, the caller can create, for example, a 
system global section (SEC$M_SYSGBL bit) or permanent global section 
(SEC$M_PERM bit). For example, to create a system permanent global 
section, the caller can specify (SEC$M_SYSGBL | SEC$M_PERM) in the 
optional argument. 

The mmap function does not check or set any privileges. It is the 
responsibility of the caller to set appropriate privileges, such as SYSGBL 
privilege for SEC$M_SYSGBL, and PRMGBL for SEC$M_PERM, before 
calling mmap with the optional argument. 


See also read, write, open, fopen, creat, and sysconf. 


Return Values 
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x The address where the mapping is placed. 


MAP_FAILED 


mmap 


Indicates an error; errno is set to one of the 
following values: 


EACCES — The file referred to by filedes is 
not open for read access, or the file is not 
open for write access and PROT_WRITE was 
set for a MAP_SHARED mapping operation. 


EBADF -— The filedes argument is not a valid 
file descriptor. 


EINVAL —The flags or prot argument 

is invalid, or the addr argument or off 
argument is not a multiple of the page size 
returned by sysconf (_SC_PAGE SIZE). Or 
MAP_ANONYMOUS was specified in flags 
and filedes is not —1. 


ENODEV -— The file descriptor filedes refers 
to an object that cannot be mapped, such as 
a terminal. 


ENOMEM - There is not enough address 
space to map len bytes. 


ENXIO — The addresses specified by the 
range loff, off + len] are invalid for filedes. 


EFAULT — The addr argument is an invalid 
address. 
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modf 

Decomposes a floating-point number. 
Format 

#include <math.h> 

double modf (double x, double *ipir); 

float modff (float x, float *iptr); (Alpha, 164) 

long double modfl (long double x, long double *jptr); (Aipha, 164) 
Arguments 


x 
An object of type double, float, or long double. 


iptr 
A pointer to an object of type double, float, or long double to match the type of 
x. 


Description 


The modf functions decompose their first argument x into a positive fractional 
part f and an integer part i, each of which has the same sign as x. 


The functions return f and assign 7 to the object pointed to by the second 
argument (iptr). 


Return Values 


x The fractional part of the argument x. 

NaN x is NaN; errno is set to EDOM and “pir is set 
to NaN. 

0 Underflow occurred; errno is set to ERANGE. 
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[w]move 


Change the current cursor position on the specified window to the coordinates 
(y,x). The move function acts on the stdscr window. 
Format 
#include <curses.h> 
int move (int y, int x); 


int wmove (WINDOW ‘win, int y, int x); 


Arguments 
win 
A pointer to the window. 


y 
A window coordinate. 


x 
A window coordinate. 


Description 


For more information, see the scrollok function in this section. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally. 
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mprotect 


Format 


Arguments 


Description 
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Modifies access protections of memory mapping. This function is reentrant. 


#include <mman.h> 


int mprotect (void *adar, size_t len, int prot); 


addr 
The address of the region that you want to modify. 


len 
The length, in bytes, of the region that you want to modify. 


prot 
Access permission, as defined in the <mman.h> header file. Specify either PROT_ 
NONE, PROT_READ, or PROT_WRITE. 


The mprotect function modifies the access protection of a mapped file or shared 
memory region. 


The addr and len arguments specify the address and length, in bytes, of the 
region that you want to modify. The /en argument must be a multiple of the page 
size as returned by sysconf(_SC_PAGE SIZE). If len is not a multiple of the page 
size as returned by sysconf(_SC_PAGE SIZE), the length of the region is rounded 
up to the next multiple of the page size. 


The prot argument specifies access permissions for the mapped region. Specify 
one of the following: 


PROT_NONE No access 
PROT_READ Read-only 
PROT_WRITE Read/Write access 


The mprotect function does not modify the access permission of any region that 
lies outside of the specified region, except that the effect on addresses between 
the end of the region, and the end of the page containing the end of the region, is 
unspecified. 


If the mprotect function fails under a condition other than that specified by 
EINVAL, the access protection of some of the pages in the range [addr, addr + 
len] can change. Suppose the error occurs on some page at an addr2; mprotect 
can modify protections of all whole pages in the range [addr, addr2]. 


See also sysconf. 


mprotect 


Return Values 


0 Indicates success. 
—1 Indicates an error; errno is set to one of the 
following values: 


e EACCESS — The prot argument specifies 
a protection that conflicts with the access 
permission set for the underlying file. 


e EINVAL — The prot argument is 
invalid, or the addr argument is not a 
multiple of the page size as returned by 
sysconf(_SC_ PAGE SIZE). 


e EFAULT - The range [addr, addr + len] 
includes an invalid address. 
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mrand48 


Format 


Description 


Generates uniformly distributed pseudorandom-number sequences. Returns 
48-bit signed long integers. 


#include <stdlib.h> 


long int mrand48 (void); 


The mrand48 function generates pseudorandom numbers using the linear 
congruential algorithm and 48-bit integer arithmetic. 


It returns signed long integers uniformly distributed over the range of y values 
such that —2°! < y < 231. 


Before you call the mrand48 function, use either srand48, seed48, or lcong48 to 
initialize the random-number generator. You must initialize the mrand48 function 
prior to invoking it, because it stores the last 48-bit Xi generated into an internal 
buffer. (Although it is not recommended, constant default initializer values are 
supplied automatically if the drand48, lrand48, or mrand48 functions are called 
without first calling an initialization function.) 


The function works by generating a sequence of 48-bit integer values, Xi, 
according to the linear congruential formula: 


Xn+1 = (aXn+c)mod m n >= 0 


The argument m equals 2*°, so 48-bit integer arithmetic is performed. Unless you 
invoke the lcong48 function, the multiplier value a and the addend value c are: 


5DEECE66D16 = 273673163155 
B16 = 138 


¢ 


The values returned by the mrand48 function is computed by first generating the 
next 48-bit Xi in the sequence. Then the appropriate bits, according to the type 
of returned data item, are copied from the high-order (most significant) bits of Xi 
and transformed into the returned value. 


See also drand48, lrand48, lcong48, seed48, and srand48. 


Return Value 
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n Returns signed long integers uniformly 
distributed over the range —23! <y < 231, 


msync 


msync 


Format 


Arguments 


Description 


Synchronizes a mapped file. 


#include <mman.h> 


int msync (void *addr, size_t Jen, int flags); 


addr 
The address of the region that you want to synchronize. 


len 
The length, in bytes, of the region that you want to synchronize. 


flags 

One of the following symbolic constants defined in the <mman.h> header file: 
MS_SYNC Synchronous cache flush 

MS_ASYNC Asynchronous cache flush 

MS_INVALIDATE Invalidate cashed pages 


The msync function controls the caching operations of a mapped file region. Use 
msync to: 


e Ensure that modified pages in the region transfer to the underlying storage 
device of the file. 


e Control the visibility of modifications with respect to file system operations. 


The addr and len arguments specify the region to be synchronized. 

The Jen argument must be a multiple of the page size as returned by 
sysconf (_SC_ PAGE SIZE); otherwise, the length of the region is rounded up 
to the next multiple of the page size. 


If the flags argument is set to: 


flags Argument Then the msync Function... 

MS SYNC Does not return until the system completes all I/O 
operations. 

MS _ASYNC Returns after the system schedules all I/O operations. 

MS_INVALIDATE Invalidates all cached copies of the pages. The 


operating system must obtain new copies of the pages 
from the file system the next time the application 
references them. 


After a successful call to the msync function with the flags argument set to: 


e MS SYNC — All previous modifications to the mapped region are visible to 
processes using the read argument. Previous modifications to the file using 
the write function are lost. 
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e MS_INVALIDATE — All previous modifications to the file using the write 
function are visible to the mapped region. Previous direct modifications to the 
mapped region are lost. 


See also read, write, and sysconf. 
Return Values 


0 Indicates success. 
—1 Indicates an error; errno is set to one of the 
following values: 


e KIO -— An //O error occurred while reading 
from or writing to the file system. 


e ENOMEM - The range specified by 
laddr, addr + len] is invalid for a process’s 
address space, or the range specifies one or 
more unmapped pages. 


e EINVAL — The addr argument is not a 
multiple of the page size as returned by 
sysconf(_SC_ PAGE SIZE). 


e EFAULT - The range [addr, addr + len] 
includes an invalid address. 
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munmap 


Format 


Arguments 


Description 


Unmaps a mapped region. This function is reentrant. 


#include <mman.h> 


int munmap (void *addr, size_t len); 


addr 
The address of the region that you want to unmap. 


len 
The length, in bytes, of that region the you want to unmap. 


The munmap function unmaps a mapped file or shared memory region. 


The addr and len arguments specify the address and length, in bytes, respectively, 
of the region to be unmapped. 


The Jen argument must be a multiple of the page size as returned by 
sysconf (_SC_PAGE SIZE); otherwise, the length of the region is rounded up 
to the next multiple of the page size. 


The result of using an address that lies in an unmapped region and not in any 
subsequently mapped region is undefined. 


See also sysconf. 


Return Values 


0 Indicates success. 


—1 Indicates an error; errno is set to one of the 
following values: 


e ENIVAL — The addr argument is not a 
multiple of the page size as returned by 
sysconf(_SC_ PAGE SIZE). 


e EFAULT - The range [addr, addr + len] 
includes an invalid address. 
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mv[w]Jaddch 


Move the cursor to coordinates (y,x) and add a character to the specified window. 


Format 
#include <curses.h> 
int mvaddch (int y, int x, char ch); 
int mvwaddch (WINDOW “win, int y, int x, char ch); 


Arguments 
win 
A pointer to the window. 


y 


A window coordinate. 


4 
A window coordinate. 


ch 

If this argument is a new-line character (\n), the mvaddch and mvwaddch functions 
clear the line to the end, and move the cursor to the next line at the same x 
coordinate. A carriage return (\r) moves the cursor to the beginning of the 
specified line. A tab (\t) moves the cursor to the next tabstop within the window. 


Description 
This routine performs the same function as mvwaddch, but on the stdscr window. 
When mvwaddch is used on a subwindow, it writes the character onto the 


underlying window as well. 


Return Values 


OK Indicates success. 


ERR Indicates that writing the character would 
cause the screen to scroll illegally. For more 
information, see the scrollok function. 
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mv[w]addstr 


Move the cursor to coordinates (y,x) and add the specified string, to which str 
points, to the specified window. 


Format 

#include <curses.h> 

int mvaddstr (int y, int x, char *str); 

int mvwaddstr (WINDOW *win, int y, int x, char *str); 
Arguments 


win 
A pointer to the window. 


y 


A window coordinate. 


x 
A window coordinate. 


str 
A pointer to the character string. 


Description 
This routine performs the same function as mvwaddstr, but on the stdscr window. 


When mvwaddstr is used on a subwindow, the string is written onto the 
underlying window as well. 


Return Values 


OK Indicates success. 


ERR Indicates that the function causes the screen 
to scroll illegally, but it places as much of the 
string onto the window as possible. For more 
information, see the scrollok function. 
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mvcur 


Format 


Arguments 


Description 


Moves the terminal’s cursor from (lasty,lastx) to (newy,newx). 


#include <curses.h> 


int mvcur (int /asty, int lastx, int newy, int newx); 


lasty 
The cursor position. 


lastx 
The cursor position. 


newy 
The resulting cursor position. 


newx 
The resulting cursor position. 


In HP C for OpenVMS Systems, mvcur and move perform the same function. 


See also move. 


Return Values 
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OK Indicates success. 


ERR Indicates that moving the window placed part 
or all of the window off the edge of the terminal 
screen. The terminal screen remains unaltered. 


mv[w]delch 


mv[w]delch 


Move the cursor to coordinates (y,x«) and delete the character on the specified 
window. The mvdelch function acts on the stdscr window. 


Format 
#include <curses.h> 


int mvdelch (int y, int x); 
int mvwdelch (WINDOW *win, int y, int x); 


Arguments 
win 
A pointer to the window. 


y 


A window coordinate. 


x 
A window coordinate. 
Description 
Each of the following characters on the same line shifts to the left, and the last 


character becomes blank. 


Return Values 


OK Indicates success. 


ERR Indicates that deleting the character would 
cause the screen to scroll illegally. For more 
information, see the scrollok function. 
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mv[w]getch 


Format 


Arguments 


Description 


Move the cursor to coordinates (y,x), get a character from the terminal screen, 
and echo it on the specified window. The mvgetch function acts on the stdscr 
window. 


#include <curses.h> 
int mvgetch (int y, int x); 
int mvwgetch (WINDOW *win, int y, int x); 


win 
A pointer to the window. 


y 
A window coordinate. 


x 
A window coordinate. 


The mvgetch and mvwgetch functions refresh the specified window before fetching 
the character. 


Return Values 
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x The returned character. 

ERR Indicates that the function causes the screen to 
scroll illegally. For more information, see the 
scrollok function in this section. 


mv[w]getstr 


mv[w]getstr 


Move the cursor to coordinates (y,x), get a string from the terminal screen, store 

it in the variable str (which must be large enough to contain the string), and echo 

it on the specified window. The mvgetstr function acts on the stdscr window. 
Format 

#include <curses.h> 

int mvgetstr (int y, int x, char *str); 


int mvwgetstr (WINDOW “win, int y, int x, char *stn); 


Arguments 
win 
A pointer to the window. 


y 


A window coordinate. 


x 
A window coordinate. 


str 
The string that is displayed. 


Description 


The mvgetstr and mvwgetstr functions strip the new-line terminator (\n) from 
the string. 


Return Values 


OK Indicates success. 


ERR Indicates that the function causes the screen to 
scroll illegally. 
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mv[w]inch 


Move the cursor to coordinates (y,x) and return the character on the specified 
window without making changes to the window. The mvinch function acts on the 
stdscr window. 


Format 

#include <curses.h> 

int mvinch (int y, int x); 

int mvwinch (WINDOW *win, int y, int x); 
Arguments 


win 
A pointer to the window. 


y 


A window coordinate. 


x 
A window coordinate. 


Return Values 


x The returned character. 
ERR Indicates an input error. 
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mv[w]insch 


mv[w]linsch 


Format 


Arguments 


Description 


Move the cursor to coordinates (y,x) and insert the character ch into the specified 
window. The mvinsch function acts on the stdscr window. 


#include <curses.h> 
int mvinsch (int y, int x, char ch); 


int mvwinsch (WINDOW “*win, int y, int x, char ch); 


win 
A pointer to the window. 


y 


A window coordinate. 


x 
A window coordinate. 


ch 
The character to be inserted at the window’s coordinates. 


After the character is inserted, each character on the line shifts to the right, and 
the last character on the line is deleted. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally. For more information, see the 
scrollok function in this section. 
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mv[w]insstr 


mv[w]insstr 


Move the cursor to coordinates (y,x) and insert the specified string into the 
specified window. The mvinsstr function acts on the stdscr window. 


Format 

#include <curses.h> 

int mvinsstr (int y, int x, char *str); 

int mvwinsstr (WINDOW “win, int y, int x, char “str; 
Arguments 


win 
A pointer to the window. 


y 


A window coordinate. 


x 
A window coordinate. 


str 
The string that is displayed. 


Description 


Each character after the string shifts to the right, and the last character 
disappears. The mvinsstr and mvwinsstr functions are specific to HP C for 
OpenVMS Systems and are not portable. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally. For more information, see the 
scrollok function. 
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mvwin 
Moves the starting position of the window to the specified (y,x) coordinates. 


Format 
#include <curses.h> 
mvwin (WINDOW *win, int y, int x); 


Arguments 
win 
A pointer to the window. 


y 


A window coordinate. 


x 
A window coordinate. 


Description 


When moving subwindows, the mvwin function does not rewrite the contents of the 
subwindow on the underlying window at the new position. If you write anything 
to the subwindow after the move, the function also writes to the underlying 
window. 


Return Values 


OK Indicates success. 


ERR Indicates that moving the window put part or all 
of the window off the edge of the terminal screen. 
The terminal screen remains unaltered. 
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nanosleep (Aipia, 164) 


nanosleep dipia, 164) 


Format 


Arguments 


Description 
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High-resolution sleep (REALTIME). Suspends a process (or thread in a threaded 
program) from execution for the specified timer interval. 


#include <time.h> 


int nanosleep (const struct timespec *rqtp, struct timespec *rmip); 


rqtp 
A pointer to the timespec data structure that defines the time interval during 
which the calling process or thread is suspended. 


rmtp 

A pointer to the timespec data structure that receives the amount of time 
remaining in the previously requested interval, or zero if the full interval has 
elapsed. 


The nanosleep function suspends a process or thread until one of the following 
conditions is met: 


e The time interval specified by the rqgtp argument has elapsed. 


e A signal is delivered to the calling process and the action is to invoke a 
signal-catching function or to terminate the process. 


The suspension time may be longer than requested because the argument value 
is rounded up to an integer multiple of the sleep resolution or because of the 
scheduling of other activity by the system. Except when interrupted by a signal, 
the suspension time is not less than the time specified by the rqtp argument (as 
measured by the system clock, CLOCK_REALTIME). 


The use of the nanosleep function has no effect on the action or blockage of any 
signal. 


If the requested time has elapsed, the call was successful and the nanosleep 
function returns zero. 


On failure, the nanosleep function returns —1 and sets errno to indicate the 
failure. The function fails if it has been interrupted by a signal, or if the rqtp 
argument specified a nanosecond value less than 0 or greater than or equal to 1 
billion. 


If the rmtp argument is non-NULL, the timespec structure it references is 
updated to contain the amount of time remaining in the interval (the requested 
time minus the time actually slept). 


If the rmtp argument is NULL, the remaining time is not returned. 


See also clock getres, clock gettime, clock settime, and sleep. 


Return Values 


0 


-1 


nanosleep (ira, 164) 


Indicates success. The requested time has 
elapsed. 

Indicates failure. The function call was 
unsuccessful or was interrupted by a signal; 
errno is set to one of the following values: 


e EINTR — The nanosleep function was 
interrupted by a signal. 


e EINVAL — The rgtp argument specified a 
nanosecond value less than 0 or greater than 
or equal to 1 billion. 
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newwin 


newwin 


Format 


Arguments 


Creates a new window with numiines lines and numcols columns starting at the 
coordinates (begin_y,begin_x) on the terminal screen. 


#include <curses.h> 


WINDOW *newwin (int numiines, int numcols, int begin_y, int begin_x); 


numlines 
If it is 0, the newwin function sets that dimension to LINES (begin_y). To get a 
new window of dimensions LINES by COLS, use the following line: 


newwin (0, 0, 0, 0) 


numcols 
If it is 0, the newwin function sets that dimension to COLS (begin_x). Therefore, 
to get a new window of dimensions LINES by COLS, use the following line: 


newwin (0, 0, 0, 0) 


begin_y 
A window coordinate. 


begin_x 
A window coordinate. 


Return Values 
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x The address of the allocated window. 
ERR Indicates an error. 


nextafter (Aipra, 164) 


nextafter (pra, 164 


Returns the next machine-representable number following x in the direction of y. 


Format 

#include <math.h> 

double nextafter (double x, double y); 

float nextafterf (float x, float y); 

long double nextafterl (long double x, long double y): 
Arguments 

x 

A real number. 

A real number. 
Description 


The nextafter functions return the next machine-representable floating-point 
number following x in the direction of y. If y is less than x, nextafter returns the 
largest representable floating-point number less than x. 


Return Values 


n The next representable floating-point value 
following x in the direction of y. 

HUGE_VAL Overflow; errno is set to ERANGE. 

NaN x or y is NaN; errno is set to EDOM. 
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nexttoward (alpha, 164) 


nexttoward (Alpha, 164) 


Equivalent to the nextafter function, with exceptions noted in the Description. 


Format 

#include <math.h> 

double nexttoward (double x, long double y); 

float nexttowardf (float x, long double y); 

long double nexttowardl (long double x, long double y); 
Arguments 


4 
A real number. 


A real number. 


Description 


The nexttoward functions are equivalent to the corresponding nextafter 
functions, except that the second parameter has type long double and the 
functions return y converted to the type of the function if x equals y. 


Return Values 


n The next representable floating-point value 
following x in the direction of y. 

y (of the type x) If x equals y. 

HUGE_VAL Overflow; errno is set to ERANGE. 

NaN x or y is NaN; errno is set to EDOM. 
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nice 


nice 


Format 


Argument 


Description 


Increases or decreases process priority relative to the process current priority by 
the amount of the argument. This function is nonreentrant. 


#include <unistd.h> 


int nice (int increment); 


increment 

As a positive argument, decreases priority; as a negative argument, increases 
priority. Issuing nice(0) restores the base priority. The resulting priority cannot 
be less than 1, or greater than the process’s base priority. If it is, the nice 
function quietly does nothing. 


When a process calls the vfork function, the resulting child inherits the parent’s 
priority. 


With the DECC$ALLOW_UNPRIVILEGED_NICE feature logical enabled, the 
nice function exhibits its legacy behavior of not checking the privilege of the 
calling process (that is, any user may lower the nice value to increase process 
priorities). Also, when the caller sets a priority above MAX_PRIORITY, the nice 
value is set to the base priority. 


With DECC$ALLOW_UNPRIVILEGED_NICE disabled, the nice function 
conforms to the X/Open standard of checking the privilege of the calling process 
(only users with ALTPRI privilege can lower the nice value to increase process 
priorities), and when the caller sets a priority above MAX_PRIORITY, the nice 
value is set to MAX_ PRIORITY. 


See also vfork. 


Return Values 


0 Indicates success. 
=1 Indicates failure. 
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nint pha, 164) 


Nnint cipia, 164) 


Returns the nearest integral value to the argument. 


Format 

#include <math.h> 

double nint (double x); 

float nintf (float x,); 

long double nintl (long double x); 
Argument 

x 

A real number. 
Description 


The nint functions return the nearest integral value to x, except halfway cases 
are rounded to the integral value larger in magnitude. This corresponds to the 
Fortran generic intrinsic function nint. 


Return Values 


n The nearest integral value to x. 
NaN x is NaN; errno is set to EDOM. 
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[no]nl 


[no]nl 


The nl and nonl functions are provided only for UNIX software compatibility and 
have no function in the OpenVMS environment. 
Format 
#include <curses.h> 
void nl (void); 


void nonl (void); 
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nl_langinfo 


nl_langinfo 


Returns a pointer to a string that contains information obtained from the 
program’s current locale. 


Format 


#include <langinfo.h> 


char *nl_langinfo (nl_item item); 


Argument 


item 
The name of a constant that specifies the information required. These constants 
are defined in <langinfo.hs>. 


The following constants are valid: 


Constant Category Description 

DT FMT LC_TIME String for formatting date and time 

D_FMT LC_TIME String for formatting date 

T FMT LC_TIME String for formatting time 

T FMT AMPM LC_TIME Time format with AM/PM string 

AM_STR LC_TIME String that represents AM in 12-hour 
clock notation 

PM_STR LC_TIME String that represents PM in 12-hour 
clock notation 

DAY_1 LC_TIME The name of the first day of the week 

DAY_7 LC_TIME The name of the seventh day of the 
week 

ABDAY_1 LC_TIME The abbreviated name of the first day 
of the week 

ABDAY_7 LC_TIME The abbreviated name of the seventh 
day of the week 

MON_1 LC_TIME The name of the first month in the 
year 

MON_12 LC_TIME The name of the twelfth month in the 
year 

ABMON_1 LC_TIME The abbreviated name of the first 


month in the year 


ABMON_ 12 LC_TIME The abbreviated name of the twelfth 


month in the year 
ERA LC_TIME Era description strings 
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Description 


nl_langinfo 


Constant Category Description 
ERA _D_ FMT LC_TIME Era date format string 
ERA_T FMT LC_TIME Era time format 
ERA_D_T_FMT LC_TIME Era date and time format 
ALT_DIGITS LC_TIME Alternative symbols for digits 
RADIXCHAR LC_NUMERIC The radix character 
THOUSEP LC_NUMERIC The character used to separate 
groups of digits in nonmonetary 
values 
YESEXP LC_MESSAGES The expression for affirmative 
responses to yes/no questions 
NOEXP LC_MESSAGES The expression for negative responses 
to yes/no questions 
CRNCYSTR LC_MONETARY The currency symbol. It is preceded 
by one of the following: 
e A minus (—) if the symbol is to 
appear before the value 
e Aplus (+) if the symbol is to 
appear after the value 
e A period (.) if the symbol replaces 
the radix character 
CODESET LC_CTYPE Codeset name 


If the current locale does not have language information defined, the function 
returns information from the C locale. The program should not modify the string 
returned by the function. This string might be overwritten by subsequent calls to 


nl_langinfo. 


If the setlocale function is called after a call to nl_langinfo, then the pointer 
returned by the previous call to nl_langinfo will be unspecified. In this case, the 
nl_langinfo function should be called again. 


Return Value 


Example 


Pointer to the string containing the requested 
information. If item is invalid, the function 
returns an empty string. 


#include <stdio.h> 
#include <locale.h> 
#include <langinfo.h> 


/* This test sets up the British English locale, and then */ 


/* inquires 


on the data and time format, first day of the week, */ 
* 


/* and abbreviated first day of the week. 


#include <stdlib.h> 
#include <string.h> 
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nl_langinfo 
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int 


/* 
/* 
/* 


main () 


char *return_val; 
char *nl_ ptr; 
/* set the locale, with user supplied locale name */ 


return_val = setlocale(LC_ALL, "en_gb.iso8859-1") ; 
if (return_val == NULL) { 


printf ("ERROR : The locale is unknown") ; 
exit (1); 


/* Get the date and time format from the locale. */ 
printf ("D_T FMT = "); 


/* Compare the returned string from nl_langinfo with */ 


/* an empty string. */ 

if (!stremp((nl_ptr = (char *) nl_langinfo(D_T FMT)), "")) { 
The string returned was empty this could mean that either */ 
1) The locale does not contain a value for this item */ 
2) The value for this item is an empty string * / 

printf ("nl_langinfo returned an empty string\n"); 
} 
else { 


/* Display the date and time format */ 
printf ("%s\n", nl_ptr); 


} 


/* Get the full name for the first day of the week from locale */ 
printf ("DAY 1 ="); 


/* 
/* 


/* 
/* 
/* 


Compare the returned string from nl_langinfo with */ 
an empty string. */ 
if (!stremp((nl_ptr = (char *) nl_langinfo(DAY_1)), "")) { 
The string returned was empty this could mean that either */ 
1) The locale does not contain a value for the first */ 
day of the week */ 
2) The value for the first day of the week is */ 
an empty string */ 
printf ("nl_langinfo returned an empty string\n") ; 
else { 
/* Display the full name of the first day of the week */ 


printf ("%s\n", nl_ptr); 


/* Get the abbreviated name for the first day of the week 


/* 
/* 


/* 
/* 
/* 
/* 
/* 


from locale */ 


printf ("ABDAY 1 = "); 


Compare the returned string from nl_langinfo with an empty */ 
string. */ 
if (!stremp((nl_ptr = (char *) nl_langinfo(ABDAY 1)), "")) { 


The string returned was empty this could mean that either */ 
1) The locale does not contain a value for the first / 
day of the week */ 

2) The value for the first day of the week is an */ 
empty string / 


nl_langinfo 


printf ("nl_langinfo returned an empty string\n") ; 


else { 
/* Display the abbreviated name of the first day of the week */ 


printf ("$s\n", nl ptr); 


} 


Running the example program produces the following result: 


Pos seesseeee cess sees sseseseseseocescsee es + 
DT FMT = %a %e %b %H:M:%S %Y 

DAY 1 = Sunday 

ABDAY 1 = Sun 
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nrand48 


nrand48 


Format 


Argument 


Description 


Generates uniformly distributed pseudorandom-number sequences. Returns 
48-bit signed long integers. 


#include <stdlib.h> 
long int nrand48 (unsigned short int xsubi[3)); 


xsubi 
An array of three short ints that, when concatentated together, form a 48-bit 
integer. 


The nrand48 function generates pseudorandom numbers using the linear 
congruential algorithm and 48-bit integer arithmetic. 


The nrand48 function returns nonnegative, long integers uniformly distributed 
over the range of y values, such that 0 < y < 2°. 


The function works by generating a sequence of 48-bit integer values, Xz, 
according to the linear congruential formula: 


Xn+1 = (aXn+c)mod m n >= 0 
The argument m equals 24°, so 48-bit integer arithmetic is performed. Unless you 
invoke the 1cong48 function, the multiplier value a and the addend value c are: 


a 
Cc 


5DEECE66D16 = 2736731631558 
Big = 138 


The nrand48 function requires that the calling program pass an array as the 
xsubi argument, which for the first call must be initialized to the initial value 
of the pseudorandom-number sequence. Unlike the drand48 function, it is not 
necessary to call an initialization function prior to the first call. 


By using different arguments, the nrand48 function allows separate modules of 
a large program to generate several independent sequences of pseudorandom 
numbers. For example, the sequence of numbers that one module generates does 
not depend upon how many times the functions are called by other modules. 


Return Value 
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n Returns nonnegative, long integers over the 
range 0 <y < 2°. 


open 


open 


Format 


Arguments 


Opens a file for reading, writing, or editing. It positions the file at its beginning 
(byte 0). 


#include <fcntl.h> 
int open (const char *file_spec, int flags, mode_t mode); (ANsI Cc) 


int open (const char *file_spec, int flags, ... ); (HP C Extension) 


file_spec 

A null-terminated character string containing a valid file specification. If you 
specify a directory in the file_spec and it is a search list that contains an error, 
HP C interprets it as a file open error. 


If the file_spec parameter refers to a symbolic link, the open function opens the 
file pointed to by the symbolic link. 


flags 

The following values are defined in the <fcnt1.h> header file: 
O RDONLY Open for reading only 

O WRONLY Open for writing only 

O_RDWR Open for reading and writing 

O NDELAY Open for asynchronous input 

O APPEND Append on each write 

O CREAT Create a file if it does not exist 

O_TRUNC Create a new version of this file 

O_ EXCL Error if attempting to create existing file 


These flags are set using the bitwise OR operator ( | ) to separate specified flags. 


Opening a file with 0 APPEND causes each write on the file to be appended to the 
end. (In contrast, with the VAX C RTL the behavior of files opened in append 
mode was to start at EOF and, thereafter, write at the current file position.) 


If 0 TRUNC is specified and the file exists, open creates a new file by incrementing 
the version number by 1, leaving the old version in existence. 


If O_CREAT is set and the named file does not exist, the HP C RTL creates it 
with any attributes specified in the fourth and subsequent arguments (... ). If 
O_EXCL is set with O_CREAT and the named file exists, the attempted open returns 
an error. 


mode 

An unsigned value that specifies the file-protection mode. The compiler performs 
a bitwise AND operation on the mode and the complement of the current 
protection mode. 
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open 


You can construct modes by using the bitwise OR operator ( | ) to separate 
specified modes. The modes are: 


0400 OWNER: READ 
0200 OWNER: WRITE 
0100 OWNER: EXECUTE 
0040 GROUP:READ 
0020 GROUP:WRITE 
0010 GROUP: EXECUTE 
0004 WORLD:READ 
0002 WORLD: WRITE 
0001 WORLD: EXECUTE 


The system is given the same access privileges as the owner. A WRITE privilege 
also implies a DELETE privilege. 


Optional file attribute arguments. The file attribute arguments are the same as 
those used in the creat function. For more information, see the creat function. 


Description 


If a version of the file exists, a new file created with open inherits certain 
attributes from the existing file unless those attributes are specified in the open 
call. The following attributes are inherited: record format, maximum record size, 
carriage control, and file protection. 


Notes 


e If you intend to do random writing to a file, the file must be opened 
for update by specifying a flags value of O_RDWR. 


e To create files with OpenVMS RMS default protections by using the 
UNIX system-call functions umask, mkdir, creat, and open, call mkdir, 
creat, and open with a file-protection mode argument of 0777 in a 
program that never specifically calls umask. These default protections 
include correctly establishing protections based on ACLs, previous 
versions of files, and so on. 


In programs that do vfork/exec calls, the new process image inherits 
whether umask has ever been called or not from the calling process 
image. The umask setting and whether the umask function has ever 
been called are both inherited attributes. 


See also creat, read, write, close, dup, dup2, and lseek. 
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Return Values 


Example 


A nonnegative file descriptor number. 
Indicates that the file does not exist, that it is 
protected against reading or writing, or that it 
cannot be opened for another reason. 


#include <unixio.h> 
#include <fentl.h> 
#include <stdlib.h> 


main () 
int file, 


stat; 
int flags; 


flags = O RDWR; /* Open for read and write, 

/* with user default file protection, 
/* with max fixed record size of 2048, 
/* and a block size of 2048 bytes. 


file=open("file.dat", flags, 0, "rfm=fix", "mrs=2048", "bls=2048") ; 


if (file == -1) 
perror ("OPEN error"), exit(1); 
close (file) ; 


*/ 
*/ 
e 
+ 


open 
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opendir 


opendir 


Format 


Argument 


Description 


Example 


Opens a specified directory. 


#include <dirent.h> 


DIR *opendir (const char *dir_name); 


dir_name 
The name of the directory to be opened. 


The opendir function opens the directory specifed by dir_name and associates a 
directory stream with it. The directory stream is positioned at the first entry. The 
type DIR, defined in the <dirent .h> header file, represents a directory stream. A 
directory stream is an ordered sequence of all the directory entries in a particular 
directory. 


The opendir function also returns a pointer to identify the directory stream in 
subsequent operations. The NULL pointer is returned when the directory named 
by dir_name cannot be accessed, or when not enough memory is available to hold 
the entire stream. 


Note 


An open directory must always be closed with the closedir function to 
ensure that the next attempt to open that directory is successful. The 
opendir function should be used with readdir, closedir, and rewinddir 
to examine the contents of the directory. 


See the program example in the description of closedir. 


Return Values 
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x A pointer to an object of type DIR. 


opendir 


NULL Indicates an error; errno is set to one of the 
following values: 


EACCES — Search permission is denied 
for any component of dir_name or read 
permission is denied for dir_name. 


ENAMETOOLONG - The length of the 
dir_name string exceeds PATH_MAX, or 
a pathname component is longer than 
NAME_MAX. 


ENOENT -— The dir_name argument points 
to the name of a file that does not exist, or is 
an empty string. 
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overlay 


overlay 
Nondestructively superimposes win on win2. The function writes the contents 
of win1 that will fit onto win2 beginning at the starting coordinates of both 
windows. Blanks on win1 leave the contents of the corresponding space on win2 
unaltered. The overlay function copies as much of a window’s box as possible. 
Format 
#include <curses.h> 
int overlay (WINDOW *wint, WINDOW *win2); 
Arguments 


wint 
A pointer to the window. 


win2 
A pointer to the window. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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overwrite 


overwrite 


Format 


Arguments 


Description 


Destructively writes the contents of win1 on win2. 


#include <curses.h> 
int overwrite (WINDOW *‘win1, WINDOW *win2); 


wint 
A pointer to the window. 


win2 
A pointer to the window. 


The overwrite function writes the contents of win] that will fit onto win2 
beginning at the starting coordinates of both windows. Blanks on winI are 
written on win2 as blanks. This function copies as much of a window’s box as 
possible. 


Return Values 


OK Indicates success. 
ERR Indicates failure. 
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pathconf 


pathconf 


Format 


Arguments 


Description 
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Retrieves file implementation characteristics. 


#include <unistd.h> 


long int pathconf (const char *path, int name); 


path 


The pathname of a file or directory. 


name 


The configuration attribute to query. If this attribute is not applicable to the file 
specified by the path argument, the pathconf function returns an error. 


The pathconf function allows an application to determine the characteristics of 
operations supported by the file system underlying the file named by path. Read, 
write, or execute permission of the named file is not required, but you must be 
able to search all directories in the path leading to the file. 


Symbolic values for the name argument are defined in the <unistd.h> header 


file, as follows: 
_PC_LINK MAX 


_PC_MAX CANON 
_PC_MAX_INPUT 


_PC_NAME_MAX 


_PC_PATH_MAX 


_PC_PIPE_BUF 


The maximum number of links to the file. If the path 
argument refers to a directory, the value returned 
applies to the directory itself. 


The maximum number of bytes in a canonical input 
line. This is applicable only to terminal devices. 


The number of types allowed in an input queue. This 
is applicable only to terminal devices. 


Maximum number of bytes in a file name (not including 
a terminating null). The byte range value is between 
13 and 255. This is applicable only to a directory file. 
The value returned applies to file names within the 
directory. 


Maximum number of bytes in a pathname (not 
including a terminating null). The value is never larger 
than 65,535. This is applicable only to a directory file. 
The value returned is the maximum length of a relative 
pathname when the specified directory is the working 
directory. 


Maximum number of bytes guaranteed to be written 
atomically. This is applicable only to a FIFO. The 
value returned applies to the referenced object. If the 
path argument refers to a directory, the value returned 
applies to any FIFO that exists or can be created 
within the directory. 


_PC_CHOWN_ 
RESTRICTED 


_PC_NO_TRUNC 


_PC_VDISABLE 


Return Values 


pathconf 


This is applicable only to a directory file. The value 
returned applies to any files (other than directories) 
that exist or can be created within the directory. 


Returns 1 if supplying a component name longer than 
allowed by NAME_MAX causes an error. Returns 0 
(zero) if long component names are truncated. This is 
applicable only to a directory file. 


This is always 0 (zero); no disabling character is 
defined. This is applicable only to a terminal device. 


Resultant value of the configuration attribute 
specified in name. 


Indicates an error; errno is set to one of the 
following values: 


EACCHS - Search permission is denied for a 
component of the path prefix. 


EINVAL — The name argument specifies an 
unknown or inapplicable characteristic. 


EFAULT — The path argument is an invalid 
address. 


ENAMETOOLONG -— The length of the path 
string exceeds PATH_MAX or a pathname 
component is longer than NAME_MAX. 


ENOENT - The named file does not exist or 
the path argument points to an empty string. 


ENOTDI — A component of the path prefix is 
not a directory. 
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pause 


pause 
Suspends the calling process until delivery of a signal whose action is either to 
execute a signal-catching function or to terminate the process. 
Format 
#include <unistd.h> 
int pause (void); 
Description 


The pause function suspends the calling process until delivery of a signal whose 
action is either to execute a signal-catching function or to terminate the process. 


If the action is to terminate the process, pause does not return. 


If the action is to execute a signal-catching function, pause returns after the 
signal-catching function returns. 


Return Value 


Since the pause function suspends process 
execution indefinitely unless interrupted by a 
signal, there is no successful completion return 
value. 


-1 In cases where pause returns, the return value is 
—1, and errno is set to EINTR. 
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pclose 


pclose 


Format 


Arguments 


Description 


Closes a pipe to a process. 


#include <stdio.h> 


int pclose (FILE *stream); 


stream 
A pointer to a FILE structure for an open pipe returned by a previous call to the 
popen function. 


The pclose function closes a pipe between the calling program and a shell 
command to be executed. Use pclose to close any stream you have opened 
with popen. The pclose function waits for the associated process to end, and 
then returns the exit status of the command. See the description of waitpid for 
information on interpreting the exit status. 


Beginning with OpenVMS Version 7.3-1, when compiled with the VMS_WAIT 
macro defined, the pclose function returns the OpenVMS completion code of the 
child process. 


See also popen. 


Return Values 


x Exit status of child. 


-1 Indicates an error. The stream argument is not 
associated with a popen function. errno is set to 
the following: 


e ECHILD — cannot obtain the status of the 
child process. 
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perror 


perror 


Format 


Argument 


Description 


Example 
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Writes a short error message to stderr describing the current value of errno. 


#include <stdio.h> 


void perror (const char *str); 


str 
Usually the name of the program that caused the error. 


The perror function uses the error number in the external variable errno to 
retrieve the appropriate locale-dependent error message. The function writes out 
the message as follows: str (a user-supplied prefix to the error message), followed 
by a colon and a space, followed by the message itself, followed by a new-line 
character. 


See the description of errno in Chapter 4 for a list of possible errors. 


See also strerror. 


#include <stdio.h> 


#include <stdlib.h> 
main(argc, argv) 
int argc; 
char *argv[]; 
FILE *fp; 
fp = fopen(argv[1], "r"); /* Open an input file. */ 
if (fp == NULL) { 
/* If the fopen call failed, perror prints out a */ 
/* diagnostic: */ 
i* ei 
/* "open: <error message>" * / 
/* This error message provides a diagnostic explaining */ 
/* the cause of the failure. */ 


perror ("open") ; 
exit (EXIT_FAILURE) ; 
} 
else 
fclose(fd) ; 


pipe 


pipe 


Format 


Arguments 


Creates a temporary mailbox that can be used to read and write data between a 
parent and child process. The channels through which the processes communicate 
are called a pipe. 


#include <unistd.h> 
int pipe (int array_fdscptr2]); aso POSIX-1) 


int pipe (int array_fdscptr2], ... ); (HP C Extension) 


array_fdscpitr 

An array of file descriptors. A pipe is implemented as an array of file descriptors 
associated with a mailbox. These mailbox descriptors are special in that these are 
the only file descriptors which, when passed to the isapipe function, will return 
1. 


The file descriptors are allocated in the following way: 


e The first available file descriptor is assigned to writing, and the next available 
file descriptor is assigned to reading. 


e The file descriptors are then placed in the array in reverse order; element 
0 contains the file descriptor for reading, and element 1 contains the file 
descriptor for writing. 


Represents three optional, positional arguments, flag, bufsize, and bufquota: 


flag 
An optional argument used as a bitmask. 


If either the O_NDELAY or O_NONBLOCK bit is set, the I/O operations to the 
mailbox through array_fdscptr file descriptors terminate immediately, rather than 
waiting for another process. 


If, for example, the O_NDELAY bit is set and the child issues a read request 

to the mailbox before the parent has put any data into it, the read terminates 
immediately with 0 status. If neither the O_NDELAY nor O_NONBLOCK bit is 
set, the child will be waiting on the read until the parent writes any data into the 
mailbox. This is the default behavior if no flag argument is specified. 


The values of O_ NDELAY and O_NONBLOCK are defined in the <fcnt1.h> 
header file. Any other bits in the flag argument are ignored. You must specify 
this argument if the second optional, positional argument bufsize is specified. If 
the flag argument is needed only to allow specification of the bufsize argument, 
specify flag as 0. 


bufsize 
Optional argument of type int that specifies the size of the mailbox, in bytes. 
Specify a value from 512 to 65535. 


If you specify 0 or omit this argument, the operating system creates a mailbox 
with a default size of 512 bytes. 
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If you specify a value less than 0 or larger than 65535, the results are 
unpredictable. 


If you do specify this argument, be sure to precede it with a flag argument. 


The DECC$PIPE_BUFFER_SIZE feature logical can also be used to specify the 
size of the mailbox. If bufsize is supplied, it takes precedence over the value of 
DECC$PIPE_BUFFER_SIZE. Otherwise, the value of DECC$PIPE_BUFFER_ 

SIZE is used. 


If neither bufsize nor DECC$PIPE_BUFFER_SIZE is specified, the default buffer 
size of 512 is used. 


bufquota 
Optional argument of type int that specifies the buffer quota of the pipe’s 
mailbox. Specify a value from 512 to 2147483647. 


OpenVMS Version 7.3-2 added this argument. In previous OpenVMS versions, 
the buffer quota was equal to the buffer size. 


The DECC$PIPE_BUFFER_QUOTA feature logical can also be used to specify the 
buffer quota. If the optional bufquota argument of the pipe function is supplied, 
it takes precedence over the value of DECC$PIPE_BUFFER_QUOTA. Otherwise, 
the value of DECC$PIPE_BUFFER_QUOTA is used. 


If neither bufquota nor DECC$PIPE_BUFFER_QUOTA is specified, then the 
buffer quota defaults to the buffer size. 


The mailbox used for the pipe is a temporary mailbox. The mailbox is not deleted 
until all processes that have open channels to that mailbox close those channels. 
The last process that closes a pipe writes a message to the mailbox, indicating the 
end-of-file. 


The mailbox is created by using the $CREMBX system service, specifying the 
following characteristics: 


e A maximum message length of 512 characters 
e A buffer quota of 512 characters 


e A protection mask granting all privileges to USER and GROUP and no 
privileges to SYSTEM or WORLD 


The buffer quota of 512 characters implies that you cannot write more than 

512 characters to the mailbox before all or part of the mailbox is read. Since 

a mailbox record is slightly larger than the data part of the message that it 
contains, not all of the 512 characters can be used for message data. You can 
increase the size of the buffer by specifying an alternative size using the optional, 
third argument to the pipe function. A pipe under the OpenVMS system is a 
stream-oriented file with no carriage-control attributes. It is fully buffered by 
default in the HP C RTL. A mailbox used as a pipe is different than a mailbox 
created by the application. A mailbox created by the application defaults to a 
record-oriented file with carriage return, carriage control. Additionally, writing a 
zero-length record to a mailbox writes an EOF, as does each close of the mailbox. 
For a pipe, only the last close of a pipe writes an EOF. 


pipe 


The pipe is created by the parent process before vfork and an exec function 

are called. By calling pipe first, the child inherits the open file descriptors for 
the pipe. You can then use the getname function to return the name of the 
mailbox associated with the pipe, if this information is desired. The mailbox 
name returned by getname has the format MBAnnnan: (Alpha only) or MBAnnnnn: 
(164 only) , where nnnn or nnnnn is a unique number. 


Both the parent and the child need to know in advance which file descriptors 
will be allocated for the pipe. This information cannot be retrieved at run time. 
Therefore, it is important to understand how file descriptors are used in any 
HP C for OpenVMS program. For more information about file descriptors, see 
Chapter 2. 


File descriptors 0, 1, and 2 are open in a HP C for OpenVMS program for stdin 
(SYS$INPUT), stdout (SYS$OUTPUT), and stderr (SYS$ERROR), respectively. 
Therefore, if no other files are open when pipe is called, pipe assigns file 
descriptor 3 for writing and file descriptor 4 for reading. In the array returned by 
pipe, 4 is placed in element 0 and 3 is placed in element 1. 


If other files have been opened, pipe assigns the first available file descriptor for 
writing and the next available file descriptor for reading. In this case, the pipe 
does not necessarily use adjacent file descriptors. For example, assume that two 
files have been opened and assigned to file descriptors 3 and 4 and the first file is 
then closed. If pipe is called at this point, file descriptor 3 is assigned for writing 
and file descriptor 5 is assigned for reading. Element 0 of the array will contain 5 
and element 1 will contain 3. 


In large applications that do large amounts of I/O, it gets more difficult to predict 
which file descriptors are going to be assigned to a pipe; and, unless the child 
knows which file descriptors are being used, it will not be able to read and write 
successfully from and to the pipe. 


One way to be sure that the correct file descriptors are being used is to use the 
following procedure: 


1. Choose two descriptor numbers that will be known to both the parent and the 
child. The numbers should be high enough to account for any I/O that might 
be done before the pipe is created. 


2. Call pipe in the parent at some point before calling an exec function. 


3. In the parent, use dup2 to assign the file descriptors returned by pipe to the 
file descriptors you chose. This now reserves those file descriptors for the 
pipe; any subsequent I/O will not interfere with the pipe. 


You can read and write through the pipe using the UNIX I/O functions read and 
write, specifying the appropriate file descriptors. As an alternative, you can issue 
fdopen calls to associate file pointers with these file descriptors so that you can 
use the Standard I/O functions (fread and fwrite). 


Two separate file descriptors are used for reading from and writing to the pipe, 
but only one mailbox is used so some I/O synchronization is required. For 
example, assume that the parent writes a message to the pipe. If the parent is 
the first process to read from the pipe, then it will read its own message back as 
shown in Figure REF-1. 


Note 


For added UNIX portability, you can use the following feature logicals to 
control the behavior of the C RTL pipe implementation: 
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¢ Define the DECC$STREAM_PIPE feature logical name to ENABLE to 
direct the pipe function to use stream I/O instead of record I/O. 


¢ Define the DECC$POPEN_NO_CRLF_REC_ATTR feature logical 
to ENABLE to prevent CR/LF carriage control from being added to 
pipe records for pipes opened with the popen function. Be aware that 
enabling this feature might result in undesired behavior from other 
functions such as gets that rely on the carriage-return character. 


Figure REF-1 Reading and Writing to a Pipe 


Parent Child 
a =]. 
Mailbox 
a =i 
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Return Values 


0 Indicates success. 
—1 Indicates an error. 
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poll (alpha, 164) 


Poll taipna, 164) 


Format 


Argument 


Description 


Provides users with a mechanism for multiplexing input/output over a set of file 
descriptors that reference open streams. 


#include <poll.h> 


int poll (struct pollfd filedes [], nfds_t nfds, int timeout); 


filedes 
Points to an array of pollfd structures, one for each file descriptor of interest. 
Each pollfd structure includes the following members: 


int fd — The file descriptor 
int events — The requested conditions 
int revents — The reported conditions 


nfds 
The number of pollfd structures in the filedes array. 


timeout 
The maximum length of time (in milliseconds) to wait for at least one of the 
specified events to occur. 


The poll function provides users with a mechanism for multiplexing input/output 
over a set of file descriptors that reference open streams. For each member of 
the array pointed to by filedes, poll examines the given file descriptor for the 
event(s) specified in events. The poll function identifies those streams on which 
an application can send or receive messages, or on which certain events have 
occurred. 


The filedes parameter specifies the file descriptor to be examined and the events 
of interest for each file descriptor. It is a pointer to an array of pollfd structures. 
The fd member of each pollfd structure specifies an open file descriptor. The 
poll function uses the events member to determine what conditions to report for 
this file descriptor. If one or more of these conditions is true, the poll function 
sets the associated revents member. 


The events and revents members of each pollfd structure are bitmasks. The 
calling process sets the events bitmask, and poll sets the revents bitmasks. 
These bitmasks contain inclusive ORed combinations of condition options. The 
following condition options are defined: 


POLLERR — An error has occurred on the file descriptor. This option is only 
valid in the revents bitmask; it is not used in the events member. 


For STREAMS devices, if an error occurs on the file descriptor and the device 
is also disconnected, poll returns POLLERR; POLLERR takes precedence 
over POLLHUP. 
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POLLHUP — The device has been disconnected. This event is mutually 
exclusive with POLLOUT; a stream can never be writable if a hangup 
occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND 
or POLLPRI are not mutually exclusive. This option is only valid in the 
revents bitmask; it is ignored in the events member. 


POLLIN -— Data other than high-priority data may be read without blocking. 
This option is set in revents even if the message is of zero length. In revents, 
this option is mutually exclusive with POLLPRI. 


POLLNVAL -— The value specified for fd is invalid. This option is only valid in 
the revents member; it is ignored in the events member. 


POLLOUT — Normal (priority band equals 0) data may be written without 
blocking. 


POLLPRI — High-priority data may be received without blocking. This option 
is set in revents even if the message is of zero length. In revents, this option 
is mutually exclusive with POLLIN. 


POLLRDBAND — Data from a non-zero priority band may be read without 
blocking. This option is set in revents even if the message is of zero length. 


POLLRDNORM — Normal data (priority band equals 0) may be read without 
blocking. This option is set in revents even if the message is of zero length. 


POLLWRBAND -— Priority data (priority band greater than 0) may be written. 
This event only examines bands that have been written to at least once. 


POLLWRNORM - Same as POLLOUT. 


The poll function ignores any pollfd structure whose fd member is less than 0 
(zero). If the fd member of all pollfd structures is less than 0, the poll function 
will return 0 and have no other results. 


The conditions indicated by POLLNORM and POLLOUT are true if and only if 
at least one byte of data can be read or written without blocking. There are two 
exceptions: regular files, which always poll true for POLLNORM and POLLOUT, 
and pipes, when the rules for the operation specify to return zero in order to 
indicate end-of-file. 


The condition options POLLERR, POLLHUP, and POLLNVAL are always set in 
revents if the conditions they indicate are true for the specified file descriptor, 
whether or not these options are set in events. 


For each call to the poll function, the set of reportable conditions for each file 
descriptor consists of those conditions that are always reported, together with any 
further conditions for which options are set in events. If any reportable condition 
is true for any file descriptor, the poll function will return with options set in 
revents for each true condition for that file descriptor. 


poll (ipa, 164) 


If no reportable condition is true for any of the file descriptors, the poll function 
waits up to timeout milliseconds for a reportable condition to become true. If, 

in that time interval, a reportable condition becomes true for any of the file 
descriptors, poll reports the condition in the file descriptor’s associated revents 
member and returns. If no reportable condition becomes true, poll returns 
without setting any revents bitmasks. 


If the timeout parameter is a value of —1, the poll function does not return until 
at least one specified event has occurred. If the value of the timeout parameter 
is 0 (zero), the poll function does not wait for an event to occur but returns 
immediately, even if no specified event has occurred. 


The behavior of the poll function is not affected by whether the O NONBLOCK 
option is set on any of the specified file descriptors. 


The poll function supports regular files, terminal and pseudo-terminal devices, 
STREAMS-based files, FIFOs, and pipes. The behavior of poll on elements of file 
descriptors that refer to other types of files is unspecified. 


For sockets, a file descriptor for a socket that is listening for connections indicates 
it is ready for reading after connections are available. A file descriptor for a 
socket that is connecting asynchronously indicates it is ready for writing after a 
connection is established. 


Return Values 
n Upon successful completion, a nonnegative 


value is returned, indicating the number of file 
descriptors for which poll has set the revents 


bitmask. 

0 poll has timed out and has not set any of the 
revents bitmasks. 

—1 An error occurred. errno is set to indicate the 
error: 


e EAGAIN - Allocation of internal data 
structures failed. A later call to the poll 
function might complete successfully. 


e EINTR - A signal was caught during the 
poll function, and the signal handler was 
installed with an indication that functions 
are not to be restarted. 


e EINVAL — The nfds parameter is greater 
than OPEN_MAX, or one of the fd members 
refers to a stream or multiplexer that is 
linked (directly or indirectly) downstream 
from a multiplexer. 
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popen 


Format 


Arguments 


Description 
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Initiates a pipe to a process. 


#include <stdio.h> 


FILE “popen (const char “command, const char *type); 


command 
A pointer to a null-terminated string containing a shell command line. 


type 

A pointer to a null-terminated string containing an I/O mode. Because open 
files are shared, you can use a type r command as an input filter and a type 
w command as an output filter. Specify one of the following values for the type 
argument: 


e r—the calling program can read from the standard output of the command by 
reading from the returned file stream. 


e w—the calling program can write to the standard input of the command by 
writing to the returned file stream. 


The popen function creates a pipe between the calling program and a shell 
command awaiting execution. It returns a pointer to a FILE structure for the 
stream. 


The popen function uses the value of the DECC$PIPE_BUFFER_SIZE feature 
logical to set the buffer size of the mailbox it creates for the pipe. You can specify 
a DECC$PIPE_BUFFER_SIZE value of 512 to 65024 bytes. If DECC$PIPE_ 
BUFFER_SIZE is not specified, the default buffer size of 512 is used. 


Notes 


e When you use the popen function to invoke an output filter, beware 
of possible deadlock caused by output data remaining in the program 
buffer. You can avoid this by either using the setvbuf function to 
ensure that the output stream is unbuffered, or the fflush function 
to ensure that all buffered data is flushed before calling the pclose 
function. 


e For added UNIX portability, you can use the following feature logicals 
to control the behavior of the C RTL pipe implementation: 


— Define the DECC$STREAM_PIPE feature logical name to 
ENABLE to direct the pipe function to use stream I/O instead of 
record I/O. 


popen 


Define the DECC$POPEN_NO_CRLF_REC_ATTR feature logical 
to ENABLE to prevent CR/LF carriage control from being added to 
pipe records for pipes opened with the popen function. Be aware 
that enabling this feature might result in undesired behavior 
from other functions such as gets that rely on the carriage-return 
character. 


See also fflush, pclose, and setvbuf. 


Return Values 


NULL 


A pointer to the FILE structure for the opened 
stream. 


Indicates an error. Unable to create files or 
processes. 
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Returns the first argument raised to the power of the second argument. 


long double pow! (long double x, long double y); (Alpha, 164) 


pow 
Format 
#include <math.h> 
double pow (double x, double y); 
float powf (float x, float y); (Aipha, 164) 
Arguments 


x 


A floating-point base to be raised to an exponent y. 


y 


The exponent to which the base x is to be raised. 


Description 


The pow functions raise a floating-point base x to a floating-point exponent y. The 
value of pow(x,y) is computed as e**(y In(x)) for positive x. 


If x is 0 and y is negative, t:HUGE_VAL is returned and errno is set to ERANGE 


or EDOM. 


Return Values 


1.0 
HUGE_VAL 
+HUGE_VAL 


Example 


#include <stdio.h> 
#include <math.h> 
#include <errno.h> 


main () 


double x; 


errno = 0; 


xX = pow(-3.0, 2.0); 


The result of the first argument raised to the 
power of the second. 


The base is 0 and the exponent is 0. 
The result overflowed; errno is set to ERANGE. 


The base is 0 and the exponent is negative; errno 
is set to ERANGE or EDOM. 


printf("sd, %£\n", errno, x); 


} 


This example program outputs the following: 


0, 9.000000 
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pread (pha, 164) 


pread apna, 162 


Format 


Arguments 


Description 


Reads bytes from a given position within a file without changing the file pointer. 


#include <unistd.h> 


ssize_t pread (int file_desc, void *buffer, size_t nbytes, off_t offset): 


file_desc 
A file descriptor that refers to a file currently opened for reading. 


buffer 
The address of contiguous storage in which the input data is placed. 


nbytes 
The maximum number of bytes involved in the read operation. 


offset 
The offset for the desired position inside the file. 


The pread function performs the same action as read, except that it reads from 
a given position in the file without changing the file pointer. The first three 
arguments to pread are the same as for read, with the addition of a fourth 
argument offset for the desired position inside the file. An attempt to perform a 
pread on a file that is incapable of seeking results in an error. 


Return Values 


n The number of bytes read. 


-1 Upon failure, the file pointer remains unchanged 
and pread sets errno to one of the following 
values: 


e EINVAL — The offset argument is invalid. 
The value is negative. 


e EOVERFLOW -— The file is a regular file, and 
an attempt was made to read or write at or 


beyond the offset maximum associated with 
the file. 


e ENXIO —- A request was outside the 
capabilities of the device. 


e ESPIPE — fildes is associated with a pipe or 
FIFO. 
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printf 


Format 


Arguments 


Performs formatted output from the standard output (stdout). See Chapter 2 for 
information on format specifiers. 


#include <stdio.h> 


int printf (const char *format_spec, ... ); 


format_spec 
Characters to be written literally to the output or converted as specified in 
the ... arguments. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, you may omit the output sources. 
Otherwise, the function call must have exactly as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Excess output pointers, if any, are ignored. 


Return Values 
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x The number of bytes written. 

Negative value Indicates that an output error occurred. The 
function sets errno. For a list of errno values set 
by this function, see fprintf. 


[w]printw 


[w]printw 


Format 


Arguments 


Description 


Perform a printf in the specified window, starting at the current position of the 
cursor. The printw function acts on the stdscr window. 


#include <curses.h> 
printw (char *format_spec, ... ); 


int worintw (WINDOW ‘win, char *format_spec, . .. ); 


win 
A pointer to the window. 


format_spec 
A pointer to the format specification string. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, you may omit the output sources. 
Otherwise, the function call must have exactly as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Excess output pointers, if any, are ignored. 


The formatting specification (format_spec) and the other arguments are identical 
to those used with the printf function. 


The printw and wprintw functions format and then print the resultant string 
to the window using the addstr function. For more information, see the printf 
and scrollok functions in this section. See Chapter 2 for information on format 
specifiers. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the window 
scroll illegally. 
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putc 


putc 


Format 


Arguments 


Description 


The putc macro writes a single character to a specified file. 


#include <stdio.h> 


int putc (int character, FILE *file_ptr); 


character 
The character to be written. 


file_ptr 
A file pointer to the output stream. 


The putc macro writes the byte character (converted to an unsigned char) to the 
output specified by the file_ptr parameter. The byte is written at the position at 
which the file pointer is currently pointing (if defined) and advances the indicator 
appropriately. If the file cannot support positioning requests, or if the output 
stream was opened with append mode, the byte is appended to the output stream. 


Since putc is a macro, a file pointer argument with side effects (for example, 
putc (ch, *f++)) might be evaluated incorrectly. In such a case, use the fputc 
function instead. 


Compiling with the __UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


See also putc_unlocked. 


Return Values 
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x The character written to the file. Indicates 
success. 
EOF Indicates output errors. 


putc_unlocked (aa, 164 


putc_unlocked apa, 164 


Format 


Argument 


Description 


Same as putc, except used only within a scope protected by flockfile and 
funlockfile. 


#include <stdio.h> 


int putc_unlocked (int character, FILE *file_ptr): 


character 
The character to be written. 


file_ptr 
A file pointer to the output stream. 


The reentrant version of the putc macro is locked against multiple threads calling 
it simultaneously. This incurs overhead to ensure integrity of the stream. The 
unlocked version of this call, putc_unlocked can be used to avoid the overhead. 
The putc_unlocked macro is functionally identical to the putc macro, except that 
it is not required to be implemented in a thread-safe manner. The putc_unlocked 
macro can be safely used only within a scope that is protected by the flockfile 
and funlockfile functions used as a pair. The caller must ensure that the 
stream is locked before putc_unlocked is used. 


Since putc_unlocked is a macro, a file pointer argument with side effects might 
be evaluated incorrectly. In such a case, use the fputc_unlocked function instead. 


Compiling with the __ UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


See also flockfile, ftrylockfile, and funlockfile. 


Return Values 


x The character written to the file. Indicates 
success. 
EOF Indicates the end-of-file or an error. 
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putchar 


putchar 
Writes a single character to the standard output (stdout) and returns the 
character. 
Format 
#include <stdio.h> 
int putchar (int character); 
Argument 


character 
An object of type int. 


Description 
The putchar function is identical to fputc (character, stdout). 


Compiling with the _ UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


Return Values 


character Indicates success. 
EOF Indicates output errors. 
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putchar_unlocked (ipha, 164) 


putchar_unlocked «pia, 164 


Format 


Argument 


Description 


Same as putchar, except used only within a scope protected by flockfile and 
funlockfile. 


#include <stdio.h> 


int putchar_unlocked (int character); 


character 
An object of type int. 


The reentrant version of the putchar function is locked against multiple threads 
calling it simultaneously. This incurs overhead to ensure integrity of the output 
stream. The unlocked version of this call, putchar_unlocked can be used to avoid 
the overhead. The putchar_unlocked function is functionally identical to the 
putchar function, except that it is not required to be implemented in a thread- 
safe manner. The putchar_unlocked function can be safely used only within a 
scope that is protected by the flockfile and funlockfile functions used as a 
pair. The caller must ensure that the stream is locked before putchar_unlocked 
is used. 


Compiling with the __ UNIX_PUTC macro defined enables an optimization that 
uses a faster, inlined version of this function. 


See also flockfile, ftrylockfile, and funlockfile. 


Return Values 


x The next character from stdin, converted to int. 
EOF Indicates the end-of-file or an error. 
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putenv 


putenv 


Format 


Argument 


Description 
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Sets an environmental variable. 


#include <stdlib.h> 


int putenv (const char *string); 


string 
A pointer to a name=value string. 


The putenv function sets the value of an environment variable by altering an 
existing variable or by creating a new one. The string argument points to a string 
of the form name=value, where name is the environment variable and value is the 
new value for it. 


The string pointed to by string becomes part of the environment, so altering the 
string changes the environment. When a new string-defining name is passed to 
putenv, the space used by string is no longer used. 


Notes 


e The putenv function manipulates the environment pointed to by the 
environ external variable, and can be used with getenv. However, 
the third argument to the main function (the environment pointer), is 
not changed. 


The putenv function uses the malloc function to enlarge the 
environment. 


A potential error is to call putenv with an automatic variable as the 
argument, then exit the calling function while string is still part of 
the environment. 


e Do not use the setenv, getenv, and putenv functions to manipulate 
symbols and logicals. Instead, use the OpenVMS library calls 
lib$set_logical, lib$get_logical, lib$set_symbol, and 
lib$get_ symbol. The *env functions deliberately provide UNIX 
behavior, and are not a substitute for these OpenVMS runtime library 
calls. 


OpenVMS DCL symbols, not logical names, are the closest analog 

to environment variables on UNIX systems. While getenv is a 
mechanism to retrieve either a logical name or a symbol, it maintains 
an internal cache of values for use with setenv and subsequent 
getenv calls. The setenv function does not write or create DCL 
symbols or OpenVMS logical names. 


This is consistent with UNIX behavior. On UNIX systems, setenv 
does not change or create any symbols that will be visible in the shell 
after the program exits. 


putenv 


Return Values 


0 Indicates success. 


—1 Indicates an error. errno is set to ENOMEM— 
Not enough memory available to expand the 
environment list. 


Restriction 


The putenv function cannot take a 64-bit address. See Section 1.10. 
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puts 


puts 
Writes a character string to the standard output (stdout) followed by a new-line 
character. 
Format 
#include <stdio.h> 
int puts (const char “str); 
Argument 


str 
A pointer to a character string. 


Description 


The puts function does not copy the terminating null character to the output 
stream. 


Return Values 


Nonnegative value Indicates success. 
EOF Indicates output errors. 
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putw 


putw 

Writes characters to a specified file. 
Format 

#include <stdio.h> 

int putw (int integer, FILE *file_ptr); 
Arguments 

integer 

An object of type int or long. 

file_ptr 

A file pointer. 
Description 


The putw function writes four characters to the output file as an int. No 
conversion is performed. 


Return Values 


integer Indicates success. 
EOF Indicates output errors. 
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putwc 


putwc 


Format 


Arguments 


Description 


Converts a wide character to its corresponding multibyte value, and writes the 
result to a specified file. 


#include <wchar.h> 


wint_t putwc (wint_t we, FILE *file_ptr); 


wc 
An object of type wint_t. 


file_ptr 
A file pointer. 


Since putwc might be implemented as a macro, a file pointer argument with side 
effects (for example putwe (wc, *f++)) might be evaluated incorrectly. In such a 
case, use the fputwc function instead. 


See also fputwe. 


Return Values 


REF—480 


x The character written to the file. Indicates 
success. 
WEOF Indicates an output error. The function sets 


errno. For a list of the errno values set by this 
function, see fputwe. 


putwchar 


putwchar 


Writes a wide character to the standard output (stdout) and returns the 
character. 

Format 
#include <wchar.h> 


wint_t putwchar (wint_t we); 


Arguments 


wc 
An object of type wint_t. 


Description 


The putwchar function is identical to fputwc(we, stdout). 


Return Values 


x The character written to the file. Indicates 
success. 
WEOF Indicates an output error. The function sets 


errno. For a list of the errno values set by this 
function, see fputwc. 
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pwrite (pra, 164 


Format 


Arguments 


Description 


Writes into a given position within a file without changing the file pointer. 


#include <unistd.h> 


ssize_t pwrite (int file_desc, const void *buffer, size_t nbytes, off_t offset); 


file_desc 
A file descriptor that refers to a file currently opened for writing or updating. 


buffer 
The address of contiguous storage from which the output data is taken. 


nbytes 
The maximum number of bytes involved in the write operation. 


offset 
The offset for the desired position inside the file. 


The pwrite function performs the same action as write, except that it writes 
into a given position in the file without changing the file pointer. The first three 
arguments to pwrite are the same as for write, with the addition of a fourth 
argument offset for the desired position inside the file. 


Return Values 
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n The number of bytes written. 


—1 Upon failure, the file pointer remains unchanged 
and pwrite sets errno to one of the following 
values: 


e EINVAL -— The offset argument is invalid. 
The value is negative. 


e ESPIPE — fildes is associated with a pipe or 
FIFO. 


qabs, Ilabs (ipha, 164) 


qabs, Ilabs ipa, 164) 


Returns the absolute value of an integer as an __inté4. llabs is a synonym for 


gabs. 
Format 
#include <stdlib.h> 
__int64 gabs (__int64 j); 
__int64 llabs (__int64 )); 
Argument 


j 
A value of type _inté4. 
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qdiv, IIdiv ipha, 164) 


qdiv, WdiV aipia, 164) 


Returns the quotient and the remainder after the division of its arguments. 
lldiv is a synonym for qdiv. 


Format 

#include <stdlib.h> 

qdiv_t qdiv (__int64 numer, __int64 denom); 

IIdiv_t Ildiv (__int64 numer, __int64 denom); 
Arguments 

numer 

A numerator of type __ int 64. 

denom 

A denominator of type _int 64. 
Description 


The types qdiv_t and lldiv _t are defined in the <stdlib.h> header file as 
follows: 


typedef struct 


int64 quot, rem; 
} qdiv.t, lidiv_t; 
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qsort 


Format 


Sorts an array of objects in place. It implements the quick-sort algorithm. 


#include <stdlib.h> 


void qsort (void *base, size_t nmemb, size_t size, int (“compar) (const void *, const void *)); 


Function Variants 


Arguments 


Description 


The qsort function has variants named qsort32 and qsorté4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


base 
A pointer to the first member of the array. The pointer should be of type 
pointer-to-element and cast to type pointer-to-character. 


nmemb 
The number of objects in the array. 


size 
The size of an object, in bytes. 


compar 
A pointer to the comparison function. 


Two arguments are passed to the comparison function pointed to by compar. The 
two arguments point to the objects being compared. Depending on whether the 
first argument is less than, equal to, or greater than the second argument, the 
comparison function returns an integer less then, equal to, or greater than 0. 


The comparison function compar need not compare every byte, so arbitrary data 
might be contained in the objects in addition to the values being compared. 


The order in the output of two objects that compare as equal is unpredictable. 
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raise 
Generates a specified software signal. Generating a signal causes the action 
routine established by the signal, ssignal, or sigvec function to be invoked. 
Format 
#include <signal.h> 
int raise (int sig); (ANsr C) 
int raise (int sig[, int sigcode]); xP C Extension) 
Arguments 
sig 
The signal to be generated. 
sigcode 
An optional signal code, available only when not compiling in strict ANSI C mode. 
For example, signal SIGFPE—the arithmetic trap signal—has 10 different codes, 
each representing a different type of arithmetic trap. 
The signal codes can be represented by mnemonics or numbers. The arithmetic 
trap codes are represented by the numbers 1 to 10; the SIGILL codes are 
represented by the numbers 0 to 2. The code values are defined in the <signal .h> 
header file. See Tables 4—4 and 4—5 for a list of signal mnemonics, codes, and 
corresponding OpenVMS exceptions. 
Description 


Calling the raise function has one of the following results: 


e If raise specifies a sig argument that is outside the range defined in the 
<signal.h> header file, then the raise function returns 0, and the errno 
variable is set to EINVAL. 


e If signal, ssignal, or sigvec establishes SIG_DFL (default action) for 
the signal, then the functions do not return. The image is exited with the 
OpenVMS error code corresponding to the signal. 


e If signal, ssignal, or sigvec establishes SIG_IGN (ignore signal) as the 
action for the signal, then raise returns its argument, sig. 


e signal, ssignal, or sigvec must establish an action function for the signal. 
That function is called and its return value is returned by raise. 


See Chapter 4 for more information on signal processing. 


See also gsignal, signal, ssignal, and sigvec. 


Return Values 


0) If successful. 
nonzero If unsuccessful. 
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rand, rand_r 


rand, rand_r 


Returns pseudorandom numbers in the range 0 to 22! — 1. 


Format 

#include <stdlib.h> 

int rand (void); 

int rand_r (unsigned int seed); (Alpha, 164) 
Argument 

seed 

An initial seed value. 
Description 


The rand function computes a sequence of pseudorandom integers in the range 0 
to {RAND_MAX} with a period of at least 2°. 


The rand_r function computes a sequence of pseudorandom integers in the range 
0 to {RAND_MAX}. The value of the {RAND_MAX} macro will be at least 32767. 


If rand_r is called with the same initial value for the object pointed to by seed 
and that object is not modified between successive returns and calls to rand_r, 
the same sequence is generated. 


See also srand. 


For other random-number algorithms, see random and all the *48 functions. 


Return Value 


n A pseudorandom number. 
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random 


random 


Format 


Description 


Generates pseudorandom numbers in a more random sequence. 


#include <stdlib.h> 


long int random (void): 


The random function is a random-number generator that has virtually the same 
calling sequence and initialization properties as the rand function, but produces 
sequences that are more random. The low 12 bits generated by rand go through 
a cyclic pattern. All bits generated by random are usable. For example, random() 
&1 produces a random binary value. 


The random function uses a nonlinear, additive-feedback, random-number 
generator employing a default state-array size of 31 integers to return successive 
pseudorandom numbers in the range from 0 to 2°! —1. The period of this random- 
number generator is approximately 16*(23! — 1). The size of the state array 
determines the period of the random-number generator. Increasing the state 
array size increases the period. 


With a full 256 bytes of state information, the period of the random-number 
generator is greater than 2°, and is sufficient for most purposes. 


Like the rand function, the random function produces by default a sequence of 
numbers that you can duplicate by calling the srandom function with a value of 
1 as the seed. The srandom function, unlike the srand function, does not return 
the old seed because the amount of state information used is more than a single 
word. 


See also rand, srand, srandom, setstate, and initstate. 


Return Value 


REF-488 


n A random number. 


[no]raw 


[no]raw 
Raw mode only works with the Curses input routines [w] getch and [w] getstr. 
Raw mode is not supported with the HP C RTL emulation of UNIX I/O, Terminal 
I/O, or Standard I/O. 

Format 
#include <curses.h> 
raw() 
noraw( ) 

Description 
Raw mode reads are satisfied on one of two conditions: after a minimum 
number (5) of characters are input at the terminal or after waiting a fixed 
time (10 seconds) from receipt of any characters from the terminal. 

Example 


/* Example of standard and raw input in Curses package. */ 
#include <curses.h> 
main() 

WINDOW *winl; 

char vert = '.', 


hor =" 3.%y 
str [80] ; 


/* Initialize standard screen, turn echo off. */ 


initser(); 
noecho() ; 


/* Define a user window. */ 


winl = newwin(22, 78, 1, 1); 
leaveok(winl, TRUE) ; 
leaveok(stdscr, TRUE); 


box(stdscr, vert, hor); 
/* Reset the video, refresh(redraw) both windows. */ 


mvwaddstr(winl, 2, 2, "Test line terminated input") ; 
wrefresh (win1) ; 


/* Do some input and output it. */ 
nocrmode () ; 
wgetstr(winl, str); 


mvwaddstr(winl, 5, 5, str); 
mvwaddstr(winl, 7, 7, "Type something to clear screen") ; 
wrefresh(winl) ; 


/* Get another character then delete the window. */ 


wgetch (winl 
wclear (winl 


Y 
' 


mvwaddstr(winl, 2, 2, "Test raw input"); 
wrefresh(winl) ; 
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[no]raw 


/* Do some raw input 5 chars or timeout - and output it. */ 
raw() ; 

getstr(str); 

noraw(); 

mvwaddstr(winl, 5, 5, str); 

mvwaddstr(winl, 7, 7, "Raw input completed") ; 
wrefresh(winl) ; 


endwin () ; 
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read 


read 


Reads bytes from a file and places them in a buffer. 


Format 
#include <unistd.h> 
ssize_t read (int file_desc, void “buffer, size_t nbytes); 7SO POSIX-1) 


int read (int file_desc, void *buffer, int nbytes); (Compatability) 


Arguments 


file_desc 
A file descriptor. The specified file descriptor must refer to a file currently opened 
for reading. 


buffer 
The address of contiguous storage in which the input data is placed. 


nbytes 
The maximum number of bytes involved in the read operation. 
Description 


The read function returns the number of bytes read. The return value does not 
necessarily equal nbytes. For example, if the input is from a terminal, at most 
one line of characters is read. 


Note 


The read function does not span record boundaries in a record file and, 
therefore, reads at most one record. A separate read must be done for 
each record. 


Return Values 


n The number of bytes read. 


—1 Indicates a read error, including physical input 
errors, illegal buffer addresses, protection 
violations, undefined file descriptors, and so 


forth. 
Example 

#include <unistd.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <fcntl.h> 
main () 

int fd, 

1; 
char buf [10]; 
FILE *fp ; /* Temporary STDIO file */ 
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/* Create a dummy data file */ 


if ((fp = fopen("test.txt", "w+")) == NULL) { 
perror ("open") ; 
exit (1); 


fputs("XYZ\n",fp) ; 
fclose(fp) ; 


/* And now practice "read" */ 


if ((fd = open("test.txt", O_RDWR, 0, "shr=upd")) <= 0) { 
perror ("open") ; 
exit (0); 


/* Read 2 characters into buf. */ 


if ((i = read(fd, buf, 2)) < 0) { 
perror ("read") ; 
exit (0); 


/* Print out what was read. */ 


if (i > 0) 
printf ("buf='%c%c’\n", buf[0], buf[1]); 


close (fd) ; 
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readdir, readdir_r 


readdir, readdir_r 


Format 


Arguments 


Description 


Finds entries in a directory. 


#include <dirent.h> 
struct dirent *readdir (DIR “dir_pointer); 


int readdir_r (DIR *dir_pointer, struct dirent “entry, struct dirent **result); 


dir_pointer 
A pointer to the dir structure of an open directory. 


entry 
A pointer to a dirent structure that will be initialized with the directory entry at 
the current position of the specified stream. 


result 
Upon successful completion, the location where a pointer to entry is stored. 


The readdir function returns a pointer to a structure representing the directory 
entry at the current position in the directory stream specified by dir_pointer, and 
positions the directory stream at the next entry. It returns a NULL pointer upon 
reaching the end of the directory stream. The dirent structure defined in the 
<dirent .h> header file describes a directory entry. 


The type DIR defined in the <dirent .h> header file represents a directory stream. 
A directory stream is an ordered sequence of all the directory entries in a 
particular directory. Directory entries represent files. You can remove files from 
or add files to a directory asynchronously to the operation of the readdir function. 


The pointer returned by the readdir function points to data that you can 
overwrite by another call to readdir on the same directory stream. This data is 
not overwritten by another call to readdir on a different directory stream. 


If a file is removed from or added to the directory after the most recent call to the 
opendir or rewinddir function, a subsequent call to the readdir function might 
not return an entry for that file. 


When it reaches the end of the directory, or when it detects an invalid seekdir 
operation, the readdir function returns the null value. 


An attempt to seek to an invalid location causes the readdir function to return 
the null value the next time it is called. A previous telldir function call returns 
the position. 


The readdir r function is a reentrant version of readdir. In addition to dir_ 
pointer, you must specify a pointer to a dirent structure in which the current 
directory entry of the specified stream is returned. 


If the operation is successful, readdir_r returns 0 and stores one of the following 
two pointers in result: 


e Pointer to entry if the entry was found 
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readdir, readdir_r 


e NULL pointer if the end of the directory stream was reached 


If an error occurred, an error value is returned that indicates the cause of the 
error. 


The storage pointed to by entry must be large enough for a dirent with an array 
of char d_name member containing at least NAME_MAX + 1 elements. 


Example 


See the description of closedir for an example. 


Return Values 


x On successful completion of readdir, a pointer to 
an object of type struct dirent. 

0 Successful completion of readdir_r. 

x On error, an error value (readdir_r only). 

NULL An error occurred or end of the directory stream 


(readdir_r only). If an error occurred, errno is 
set to a value indicating the cause. 
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readlink (ipa, 164 


Format 


Arguments 


Description 


Reads the contents of the specified symbolic link and places them into a user- 
supplied buffer. 


#include <unistd.h> 


ssize_t readlink (const char *restrict link_name, char *restrict user_buffer, size_t buffer_size); 


link_name 
Pointer to the text string representing the name of the symbolic link file. 


user_buffer 
Pointer to the user buffer. 


buffer_size 
Size of the user buffer. 


The readlink function reads the contents of the specified symbolic link (link_ 
name) and places them into a user-supplied buffer (user_buffer) of size (buffer_ 
size). 


See also symlink, unlink, realpath, lchown, and lstat. 


Return Values 


n Upon successful completion, the count of bytes 
placed in the uwser_buffer 


-1 Indicates an error. The buffer is unchanged, and 
errno is set to indicate the error: 


e EACCES — Read permission is denied in the 
directory where the symbolic link is being 
read, or search permission is denied for a 
component of the path prefix of link_name. 


e ENAMETOOLONG - The length of the link_ 
name argument exceeds PATH_MAX, or a 
pathname component is longer than NAME_ 
MAX. 


e Any errno value from close, open, or read. 
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readv (Alpha, 164) 


Format 


Reads from a file. 


#include <sys/uio.h> 
ssize_t readv (int file_desc, const struct iovec *iov, int iovent): 


ssize_t _readv64 (int file_desc, struct __iovec64 “iov, int iovcnt); 


Function Variants 


Arguments 


Description 
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The readv function has variants named readv32 and _readvé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


file_desc 
A file descriptor. A file descriptor that must refer to a file currently opened for 
reading. 


iov 
Array of iovec structures into which the input data is placed. 


iovent 
The number of buffers specified by the members of the iou array. 


The readv function is equivalent to read, but places the input data into the iovcent 
buffers specified by the members of the iov array: iov[0], iov[1], ..., iovliovent-1]. 
The iovent argument is valid if it is greater than 0 and less than or equal to 
TOV_MAX. 


Each iovec entry specifies the base address and length of an area in memory 
where data should be placed. The readv function always fills an area completely 
before proceeding to the next. 


Upon successful completion, readv marks for update the st_atime field of the file. 
If the Synchronized Input and Output option is supported: 


If the O_DSYNC and O_RSYNC bits have been set, read I/O 
operations on the file descriptor will complete as defined by 
synchronized I/O data integrity completion. 


If the O_SYNC and O_RSYNC bits have been set, read I/O 
operations on the file descriptor will complete as defined by 
synchronized I/O file integrity completion. 


If the Shared Memory Objects option is supported: 


If file_desc refers to a shared memory object, the result of the read 
function is unspecified. 


For regular files, no data transfer occurs past the offset maximum established in 
the open file description associated with file_desc. 


Return Values 


readv (alpha, 164) 


The number of bytes read. 


Indicates a read error. The function sets errno to 
one of the following values: 


EAGAIN — The O_NONBLOCK flag is set for 
the file descriptor, and the process would be 
delayed. 


EBADF -— The file_desc argument is not a 
valid file descriptor open for reading. 


EBADMSG - The file is a STREAM file 

that is set to control-normal mode, and the 
message waiting to be read includes a control 
part. 


EINTER — The read operation was 
terminated because of the receipt of a signal, 
and no data was transferred. 


EINVAL — The STREAM or multiplexer 
referenced by file_desc is linked (directly or 
indirectly) downstream from a multiplexer. 


OR 


The sum of the iov_len values in the iou 
array overflowed an ssize t. 


EIO — A physical I/O error has occurred. 
OR 


The process is a member of a background 
process attempting to read from its 
controlling terminal, the process is ignoring 
or blocking the SIGTTIN signal, or the 
process group is orphaned. 


EISDIR — The file_desc argument refers to a 
directory, and the implementation does not 
allow the directory to be read using read, 
pread or readv. Use the readdir function 
instead. 


EOVERFLOW - The file is a regular file, 
nbyte is greater than 0, and the starting 
position is before the end-of-file and is 
greater than or equal to the offset maximum 
established in the open file description 
associated with file_desc. 


The readv function may fail if: 


EINVAL — The iovent argument was less 
than or equal to 0, or greater than IOV_ 
MAX. 
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realloc 


Format 


Changes the size of the area pointed to by the first argument to the number of 
bytes given by the second argument. These functions are AST-reentrant. 


#include <stdlib.h> 


void *realloc (void “ptr, size_t size); 


Function Variants 


Arguments 


Description 


The realloc function has variants named realloc32 and _reallocé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


ptr 
Points to an allocated area, or can be NULL. 


size 
The new size of the allocated area. 


If ptr is the NULL pointer, the behavior of the realloc function is identical to the 
malloc function. 


The contents of the area are unchanged up to the lesser of the old and new 
sizes. The ANSI C Standard states that, "If the new size is larger than the old 
size, the value of the newly allocated portion of memory is indeterminate." For 
compatibility with old implementations, HP C initializes the newly allocated 
memory to 0. 


For efficiency, the previous actual allocation could have been larger than the 
requested size. If it was allocated with malloc, the value of the portion of 
memory between the previous requested allocation and the actual allocation is 
indeterminate. If it was allocated with calloc, that same memory was initialized 
to 0. If your application relies on realloc initializing memory to 0, then use 
calloc instead of malloc to perform the initial allocation. 


See also free, cfree, calloc, and malloc. 


Return Values 
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x The address of the area, quadword-aligned 
(Alpha only) or octaword-aligned (164 only). The 
address is returned because the area may have 
to be moved to a new address to reallocate 
enough space. If the area was moved, the space 
previously occupied is freed. 


realloc 


NULL Indicates that space cannot be reallocated (for 
example, if there is not enough room). 
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realpath 

Returns an absolute pathname from the POSIX root. 
Format 

#include <stdlib.h> 

char realpath (const char “restrict file_name, char “restrict resolved_name); 
Arguments 

file_name 

Pointer to the text string representing the name of the file for which you want 

the absolute path. 

resolved name 

Pointer to the generated absolute path stored as a null-terminated string. 
Description 


The realpath function returns an absolute pathname from the POSIX root. The 
generated pathname is stored as a null-terminated string, up to a maximum of 
PATH_MAX bytes, in the buffer pointed to by resolved_name. 


The realpath function is supported only in POSIX-compliant modes (that is, with 
DECC$POSIX_COMPLIANT_PATHNAMES defined to one of the allowed values). 


See also symlink, unlink, readlink, lchown, and lstat. 
Return Values 


x Upon successful completion, a pointer to the 
resolved_name. 

NULL Indicates an error. A null pointer is returned, 
the contents of the buffer pointed to by resolved_ 
name are undefined, and errno is set to indicate 
the error: 


e ENAMETOOLONG - The length of the file_ 
name argument exceeds PATH_MAX, or a 
pathname component is longer than NAME_ 
MAX. 


e ENOENT - A component of file_name does 
not name an existing file, or file_name points 
to an empty string. 


e Any errno value from chdir or stat. 
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[w]refresh 


Repaint the specified window on the terminal screen. The refresh function acts 
on the stdscr window. 


Format 

#include <curses.h> 

int refresh( ); 

int wrefresh (WINDOW *win); 
Argument 


win 
A pointer to the window. 
Description 


The result of this process is that the portion of the window not occluded by 
subwindows or other windows appears on the terminal screen. To see the entire 
occluded window on the terminal screen, call the touchwin function instead of the 
refresh or wrefresh function. 


See also touchwin. 
Return Values 


OK Indicates success. 
ERR Indicates an error. 
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remainder (ipia, 164 


Format 


Argument 


Description 


Returns the floating-point remainder r = x - n*y) when y is nonzero. 


#include <math.h> 
double remainder (double x, double y): 
float remainderf (float x, float y); 


long double remainder! (long double x, long double y); 


x 
A real number. 


A real number. 


These functions return the floating-point remainder r = x - n*y) when y is 
nonzero. The value n is the integral value nearest the exact value x/y. That is, 
n = vint(x/y). 


When |n - x/y| = 1/2, the value n is chosen to be even. 
The behavior of the remainder function is independent of the rounding mode. 


The remainder functions are functionally equivalent to the remquo functions. 


Return Values 
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r Upon successful completion, these functions 
return the floating-point remainder r = x - ny 
when y is nonzero. 


Nan If x or y is Nan. 


FeEMqQuUO (Alpha, 164) 


rEMQUO Apia, 164) 


Format 


Argument 


Description 


Returns the floating-point remainder r = x - n*y) when y is nonzero. 


#include <math.h> 
double remquo (double x, double y, int * quo); 
float remquof (float x, float y, int * quo); 


long double remquol (long double x, long double y, int * quo); 


4 
A real number. 


A real number. 


quo 


The remquo( ), remquof(), and remquol() functions compute the same remainder 
as the remainder( ), remainderf(), and remainderl() functions, respectively. In 
the object pointed to by quo, they store a value whose sign is the sign of x/y 
and whose magnitude is congruent modulo 2n to the magnitude of the integral 
quotient of x/y, where n is an implementation-defined integer greater than or 
equal to 3. 


The remquo functions are functionally equivalent to the remainder functions. 


Return Values 


r Upon successful completion, these functions 
return the floating-point remainder r = x - ny 
when y is nonzero. 


Nan If x or y is Nan. 
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remove 


Format 


Argument 


Description 


Deletes a file. 


#include <stdio.h> 


int remove (const char *file_spec): 


file_spec 

A pointer to the string that is an OpenVMS or a UNIX style file specification. The 
file specification can include a wildcard in its version number. So, for example, 
files of the form filename.txt;* can be deleted. 


If you specify a directory in the file name and it is a search list that contains an 
error, HP C for OpenVMS Systems interprets it as a file error. 


Note 


The DECC$ALLOW_REMOVE_OPEN_FILES feature logical controls the 
behavior of the remove function on open files. Ordinarily, the operation 
fails. However, POSIX conformance dictates that the operation succeed. 


With DECC$ALLOW_REMOVE_OPEN_FILES enabled, this POSIX 
conformant behavior is achieved. 


When remove is used to delete a symbolic link, the link itself is deleted, not the 
file to which it refers. 


The remove and delete functions are functionally equivalent in the HP C RTL. 


See also delete. 


Return Values 


REF-504 


0 Indicates success. 
nonzero value Indicates failure. 


rename 


rename 


Format 


Arguments 


Description 


Gives a new name to an existing file. 


#include <stdio.h> 


int rename (const char *old_file_spec, const char *new_file_spec); 


old_file_spec 
A pointer to a string that is the existing name of the file to be renamed. 


new_file_spec 
A pointer to a string that is to be the new name of the file. 


If you try to rename a file that is currently open, the behavior is undefined. You 
cannot rename a file from one physical device to another. Both the old and new 
file specifications must reside on the same device. 


If the new_file_spec does not contain a file extension, the file extension of old_ 
file_spec is used. To rename a file to have no file extension, new_file_spec must 
contain a period (.) For example, the following renames SYS$DISK:[]FILE.DAT 
to SYS$DISK:[]FILE1.DAT: 


rename ("file.dat", "filel"); 
However, the following renames SYS$DISK:[]FILE.DAT to SYS$DISK:[]FILE1: 


rename ("file.dat", "filel."); 


Note 


Because the rename function does special processing of the file extension, 
the caller must be careful when specifying the name of the renamed 

file in a call to a C Run-Time Library function that accepts a file-name 
argument. For example, after the following call to the rename function, 
the new file should be opened as fopen("bar.dat",...): 


rename ("foo.dat", "bar"); 


The rename function is affected by the setting of the DECC$RENAME_NO_ 
INHERIT and DECC$RENAME_ALLOW_DIR feature logicals as follows: 


¢ DECC$RENAME_NO_INHERIT provides more UNIX compliant behavior in 
rename, and affects whether or not the new name for the file inherits anything 
(like file type) from the old name or must be specified completely. 


¢ DECC$RENAME_ALLOW_DIR lets you choose between the previous 
OpenVMS behavior of allowing the renaming of a file from one directory to 
another, or the more UNIX compliant behavior of not allowing the renaming 
of a file to a directory. 
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See the DECC$RENAME_NO_INHERIT and DECC$RENAME_ALLOW_DIR 
descriptions in Section 1.6 for more information. 


Return Values 


0 Indicates success. 
—1 Indicates failure. The function sets errno to one 
of the following values: 


e EISDIR — The new argument points to a 
directory, and the old argument points to a 
file that is not a directory. 


e EEXIST — The new argument points to a 
directory that already exists. 


e ENOTDIR — The old argument names a 
directory, and new argument names a non- 
directory file. 
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rewind 

Sets the file to its beginning. 
Format 

#include <stdio.h> 

void rewind (FILE *file_ptn; so Posix-1) 

int rewind (FILE *file_ptn; (“Pp C Extension) 
Argument 

file_ptr 

A file pointer. 
Description 


The rewind function is equivalent to fseek (file ptr, 0, SEEK SET). You can 
use the rewind function with either record or stream files. 


A successful call to rewind clears the error indicator for the file. 


The ANSI C standard defines rewind as not returning a value; therefore, the 
function prototype for rewind is declared with a return type of void. However, 
since a rewind can fail, and since previous versions of the HP C RTL have 
declared rewind to return an int, the code for rewind does return 0 on success 
and —1 on failure. 


See also fseek. 
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rewinddir 


Format 


Argument 


Description 


REF-508 


Resets the position of the specified directory stream to the beginning of a 
directory. 


#include <dirent.h> 


void rewinddir (DIR *dir_pointer); 


dir_pointer 
A pointer to the dir structure of an open directory. 


The rewinddir function resets the position of the specified directory stream to 
the beginning of the directory. It also causes the directory stream to refer to 
the current state of the corresonding directory, the same as using the opendir 
function. If the dir_pointer argument does not refer to a directory stream, the 
effect is undefined. 


The type DIR, defined in the <dirent.h> header file, represents a directory 
stream. A directory stream is an ordered sequence of all the directory entries in 
a particular directory. Directory entries represent files. 


See also opendir. 


rindex 


rindex 
Searches for a character in a string. 


Format 
#include <strings.h> 


char “rindex (const char *s, int c); 


Function Variants 


The rindex function has variants named _rindex32 and _rindexé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Arguments 


s 
The string to search. 


c 
The character to search for. 


Description 


The rindex function is identical to the strchr function, and is provided for 
compatibility with some UNIX implementations. 
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rint (ipna, 164) 


rint (Alpha, 164) 


Format 


Argument 


Description 


Rounds its argument to an integral value according to the current IKEE rounding 
direction specified by the user. 


#include <math.h> 
double rint (double x); 
float rintf (float x,); 


long double rintl (long double x); 


x 
A real number. 


The rint functions return the nearest integral value to x in the direction of the 
current IEEE rounding mode specified on the /ROUNDING_MODE command-line 
qualifier. 


If the current rounding mode rounds toward negative Infinity, then rint is 
identical to floor. If the current rounding mode rounds toward positive Infinity, 
then rint is identical to ceil. 


If |x| = Infinity, rint returns x. 


Return Values 
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n The nearest integral value to x in the direction of 
the current IEEE rounding mode. 
NaN x is NaN; errno is set to EDOM. 


rmdir 


rmdir 

Removes a directory file. 
Format 

#include <unistd.h> 

int rmdir (const char *path); 
Argument 


path 
A directory pathname. 
Description 


The rmdir function removes a directory file whose name is specified in the path 
argument. The directory is removed only if it is empty. 


If path names a symbolic link, then rmdir fails and sets errno to ENOTDIR. 


Restriction 


When using OpenVMS format names, the path argument must be in the form 
directory.dir. 


Return Values 


0 Indicates success. 


—1 An error occurred; errno is set to indicate the 
error. 
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sbrk 

Determines the lowest virtual address that is not used with the program. 
Format 

#include <unistd.h> 

void *sbrk (long int incr); 
Argument 


incr 
The number of bytes to add to the current break address. 
Description 


The sbrk function adds the number of bytes specified by its argument to the 
current break address and returns the old break address. 


When a program is executed, the break address is set to the highest location 
defined by the program and data storage areas. Consequently, sbrk is needed 
only by programs that have growing data areas. 


sbrk (0) returns the current break address. 


Return Values 


x The old break address. 


(void *)(—1) Indicates that the program is requesting too 
much memory. 


Restriction 


Unlike other C library implementations, the HP C RTL memory allocation 
functions (such as malloc) do not rely on brk or sbrk to manage the program heap 
space. Consequently, on OpenVMS systems, calling brk or sbrk can interfere with 
memory allocation routines. The brk and sbrk functions are provided only for 
compatibility purposes. 
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scalb (Alpha, 164) 


Format 


Arguments 


Description 


Returns the exponent of a floating-point number. 


#include <math.h> 
double scalb (double x, double n); 
float scalbf (float x, float n); 


long double scalb! (long double x, long double n); 


x 
A nonzero floating-point number. 


n 
An integer. 


The scalb functions return x*(2**n) for integer n. 


Return Values 


x On successful completion, x*(2**n) is returned. 

tHUGE_VAL On overflow, scalb returns tHUGE_VAL 
(according to the sign of x) and sets errno to 
ERANGE. 

0 Underflow occurred; errno is set to ERANGE. 

x x is tInfinity. 

NaN x or n is NaN; errno is set to EDOM. 
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scanf 


Format 


Arguments 


Performs formatted input from the standard input (stdin), interpreting it 
according to the format specification. See Chapter 2 for information on format 
specifiers. 


#include <stdio.h> 


int scanf (const char *format_spec, ... ); 


format_spec 

Pointer to a string containing the format specification. The format specification 
consists of characters to be taken literally from the input or converted and placed 
in memory at the specified input sources. For a list of conversion characters, see 
Chapter 2. 


Optional expressions that are pointers to objects whose resultant types correspond 
to conversion specifications given in the format specification. 


If no conversion specifications are given, you can omit these input pointers. 
Otherwise, the function call must have at least as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


Return Values 
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x The number of successfully matched and 
assigned input items. 


EOF Indicates that a read error occurred prior to any 
successful conversions.The function sets errno. 
For a list of errno values set by this function, see 
fscanf. 


[w]scanw 


[w]scanw 


Format 


Arguments 


Description 


Perform a scanf on the window. The scanw function acts on the stdscr window. 


#include <curses.h> 
int scanw (char *format_spec, ... ); 


int wscanw (WINDOW ‘win, char *format_spec, ... ); 


win 
A pointer to the window. 


format_spec 
A pointer to the format specification string. 


Optional expressions that are pointers to objects whose resultant types correspond 
to conversion specifications given in the format specification. If no conversion 
specifications are given, you may omit these input pointers. 


Otherwise, the function call must have at least as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


The formatting specification (format_spec) and the other arguments are identical 
to those used with the scanf function. 


The scanw and wscanw functions accept, format, and return a line of text from the 
terminal screen. For more information, see the scrollok and scanf functions. 


Return Values 


OK Indicates success. 


ERR Indicates that the function makes the screen 
scroll illegally or that the scan was unsuccessful. 
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scroll 
Moves all the lines on the window up one line. The top line scrolls off the window 
and the bottom line becomes blank. 
Format 
#include <curses.h> 
int scroll (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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scrollok 

Sets the scroll flag for the specified window. 
Format 

#include <curses.h> 

scrollok (WINDOW *win, bool boolf); 
Arguments 


win 

A pointer to the window. 

boolf 

A Boolean TRUE or FALSE value. If boolf is FALSE, scrolling is not allowed. 


This is the default setting. The bool type is defined in the <curses.h> header file 
as follows: 


#define bool int 
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seed48 


Format 


Argument 


Description 


Initializes a 48-bit random-number generator. 


#include <stdlib.h> 
unsigned short “seed48 (unsigned short seed_16v/3)); 


seed_16v 
An array of three unsigned short ints that form a 48-bit seed value. 


The seed48 function initializes the random-number generator. You can use 
this function in your program before calling the drand48, lrand48, or mrand48 
functions. (Although it is not recommended practice, constant default initializer 
values are supplied automatically if you call drand48, lrand48, or mrand48 
without calling an initialization function). 


The seed48 function works by generating a sequence of 48-bit integer values, Xz, 
according to the linear congruential formula: 

Xn+1 = (aXn+c)mod m ni. > 0 
The argument m equals 248, so 48-bit integer arithmetic is performed. Unless you 
invoke the 1cong48 function, the multiplier value a and the addend value c are: 


5DEECE66D16 = 273673163155 
Big = 138 


Cc 
The initializer function seed48: 


e Sets the value of Xi to the 48-bit value specified in the array pointed to by 
seed_I16uv. 


e Returns a pointer to a 48-bit internal buffer that contains the previous value 
of Xi, used only by seed48. 


The returned pointer allows you to restart the pseudorandom sequence at a given 
point. Use the pointer to copy the previous Xi value into a temporary array. To 
resume where the original sequence left off, you can call seed48 with a pointer to 
this array. 


See also drand48, lrand48, and mrand48. 


Return Value 
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x A pointer to a 48-bit internal buffer. 


seekdir 


seekdir 


Format 


Arguments 


Description 


Sets the position of a directory stream. 


#include <dirent.h> 


void seekdir (DIR “dir_pointer, long int location); 


dir_pointer 
A pointer to the dir structure of an open directory. 


location 
The number of an entry relative to the start of the directory. 


The seekdir function sets the position of the next readdir operation on the 
directory stream specified by dir_pointer to the position specified by location. The 
value of location should be returned from an earlier call to telldir. 


If the value of location was not returned by a call to the telldir function, or if 
there was an intervening call to the rewinddir function on this directory stream, 
the effect is unspecified. 


The type DIR, defined in the <dirent.h> header file, represents a directory 
stream. A directory stream is an ordered sequence of all the directory entries 
in a particular directory. Directory entries represent files. You can remove files 
from or add files to a directory asynchronously to the operation of the readdir 
function. 


See readdir, rewinddir, and telldir. 
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[w]setattr 


Activate the video display attribute attr within the window. The setattr function 
acts on the stdscr window. 


Format 
#include <curses.h> 
int setattr (int attr); 
int wsetattr (WINDOW ‘win, int attr); 


Arguments 
win 
A pointer to the window. 


attr 

One of a set of video display attributes, which are blinking, boldface, reverse 
video, and underlining, and are represented by the defined constants _BLINK, 
_BOLD, _REVERSE, and _UNDERLINE, respectively. You can set multiple 
attributes by separating them with a bitwise OR operator (| ) as follows: 


setattr( BLINK | UNDERLINE) ; 


Description 


The setattr and wsetattr functions are specific to HP C for OpenVMS Systems 
and are not portable. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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setbuf 


Format 


Arguments 


Description 


Associates a new buffer with an input or output file and potentially modifies the 
buffering behavior. 


#include <stdio.h> 
void setbuf (FILE *file_ptr, char *buffer); 


file_ptr 
A file pointer. 


buffer 
A pointer to a character array or a NULL pointer. 


You can use the setbuf function after the specified file is opened but before any 
I/O operations are performed. 


If buffer is a NULL pointer, then the call is equivalent to a call to setvbuf 
with the same file_ptr, a NULL buffer pointer, a buffering type of _IONBF (no 
buffering), and a buffer size of 0. 


If buffer is not a NULL pointer, then the call is equivalent to a call to setvbuf 
with the same file_ptr, the same buffer pointer, a buffering type of _IOFBF, and 
a buffer size given by the value BUFSIZ (defined in <stdio.h>). Therefore, use 
BUFSIZ to allocate the buffer argument used in the call to setbuf. For example: 


#include <stdio.h> 
char my_buf [BUFSIZ] ; 


setbuf (stdout, my buf); 


User programs must not depend on the contents of buffer once I/O has been 
performed on the stream. The HP C RTL might or might not use buffer for any 
given I/O operation. 


The setbuf function originally allowed programmers to substitute larger buffers 
in place of the system default buffers in obsolete versions of UNIX. The large 
default buffer sizes in modern implementations of C make the use of this function 
unnecessary most of the time. The setbuf function is retained in the ANSI C 
standard for compatibility with old programs. New programs should use setvbuf 
instead, because it allows the programmer to bind the buffer size at run time 
instead of compile time, and it returns a result value that can be tested. 
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setenv 


Format 


Arguments 


Description 
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Inserts or resets the environment variable specified by name in the current 
environment list. 


#include <stdlib.h> 


int setenv (const char *name, const char *value, int overwrite); 


name 
A variable name in the environment variable list. 


value 
The value for the environment variable. 


overwrite 
A value of 0 or 1 indicating whether to reset the environment variable, if it exists. 


The setenv function inserts or resets the environment variable name in the 
current environment list. If the variable name does not exist in the list, it 
is inserted with the value argument. If the variable does exist, the overwrite 
argument is tested. When the overwrite argument value is: 


e 0 then the variable is not reset. 


e 1 then the variable is reset to value. 


Note 


Do not use the setenv, getenv, and putenv functions to manipulate 
symbols and logicals. Instead, use the OpenVMS library calls 

libSset_ logical, lib$get_ logical, lib$set_ symbol, and 

libSget_ symbol. The *env functions deliberately provide UNIX behavior, 
and are not a substitute for these OpenVMS runtime library calls. 


OpenVMS DCL symbols, not logical names, are the closest analog to 
environment variables on UNIX systems. While getenv is a mechanism 
to retrieve either a logical name or a symbol, it maintains an internal 
cache of values for use with setenv and subsequent getenv calls. The 
setenv function does not write or create DCL symbols or OpenVMS logical 
names. 


This is consistent with UNIX behavior. On UNIX systems, setenv does 
not change or create any symbols that will be visible in the shell after the 
program exits. 


Return Values 


setenv 


Indicates success. 


Indicates an error. errno is set to ENOMEM— 
Not enough memory available to expand the 
environment list. 
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seteuid (Alpha, I64) 


Sets the process’s effective user ID. 


Format 
#include <unistd.h> 


int seteuid (uid_t euid); 


Argument 


euid 
The value to which you want the effective user ID set. 


Description 


If the process has the IMPERSONATE privilege, the seteuid function sets the 
process’s effective user ID. 


An unprivileged process can set the effective user ID only if the ewid argument is 
equal to either the real, effective, or saved user ID of the process. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 


0 Successful completion. 
—1 Indicates an error. The function sets errno to 
one of the following values: 


e EINVAL - The value of the ewid argument is 
invalid and not supported. 


e EPERM - The process does not have the 
IMPERSONATE privilege, and euid does 
not match the real user ID or the saved 
set-user-ID. 
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setgid 


setgid 


Format 


Argument 


Description 


With POSIX IDs disabled, setgid is implemented for program portability and 
serves no function. It returns 0 (to indicate success). 


With POSIX IDs enabled, setgid sets the group IDs. 


#include <types.h> 
#include <unistd.h> 
int setgid (__gid_t gid); (DECC_V4_SOURCE) 


int setgid (gid_t gid); (ot _DECC_V4_SOURCE) 


gid 
The value to which you want the group IDs set. 


The setgid function can be used with POSIX style identifiers enabled or disabled. 
POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher. 


With POSIX IDs disabled, the setgid function is implemented for program 
portability and serves no function. It returns 0 (to indicate success). 


With POSIX style IDs enabled: 


e Ifthe process has the IMPERSONATE privilege, the setgid function sets the 
real group ID, effective group ID, and the saved set-group-ID to gid. 


e Ifthe process does not have appropriate privileges but gid is equal to the 
real group ID or to the saved set-group-ID, then the setgid function sets the 
effective group ID to gid. The real group ID and saved set-group-ID remain 
unchanged. 


e Any supplementary group IDs of the calling process remain unchanged. 


To enable/disable POSIX style IDs, see Section 1.7. 


Return Values 


0 Successful completion. 
—1 Indicates an error. The function sets errno to 
one of the following values: 


e EINVAL — The value of the gid argument 
is invalid and not supported by the 
implementation. 


e EPERM - The process does not have 
appropriate privileges and gid does not match 
the real group ID or the saved set-group-ID. 
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setgrent (ipa, 164) 


setg rent apne, 164) 


Rewinds the group database. 


Format 
#include <grp.h> 


void setgrent (void); 


Description 


The setgrent function effectively rewinds the group database to allow repeated 
searches. 


This function is always successful. No value is returned, and errno is not set. 
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setitimer 


Format 


Arguments 


Description 


Sets the value of interval timers. 


#include <time.h> 


int setitimer (int which, struct itimerval *value, struct itimerval *ovalue); 


which 
The type of interval timer. The HP C RTL only supports ITIMER_REAL. 


value 
A pointer to an itimerval structure whose members specify a timer interval and 
the time left to the end of the interval. 


ovalue 
A pointer to an itimerval structure whose members specify a current timer 
interval and the time left to the end of the interval. 


The setitimer function sets the timer specified by which to the value specified by 
value, returning the previous value of the timer if ovalue is nonzero. 


A timer value is defined by the itimerval structure: 


struct itimerval { 
struct timeval it interval; 
struct timeval it value; 


i 


The value of the itimerval structure members are: as follows 


itimerval Member Value Meaning 

it_interval = 0 Disables a timer after its next expiration 
(assumes it value is nonzero). 

it_interval = nonzero Specifies a value used in reloading it_value 
when the timer expires. 

it value =0 Disables a timer. 

it_value = nonzero Indicates the time to the next timer expiration. 


Time values smaller than the resolution of the system clock are rounded up to 
this resolution. 


The getitimer function provides one interval timer, defined in the <time.h> 
header file as ITIMER_REAL. This timer decrements in real time. When the 
timer expires, it delivers a SIGALARM signal. 
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Note 
The interaction between setitimer and any of alarm, sleep, or usleep is 
unspecified. 
Return Values 
0 Indicates success. 
—1 An error occurred; errno is set to indicate the 


error. 
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setjmp 


setjmp 


Format 


Argument 


Description 


Provides a way to transfer control from a nested series of function invocations 
back to a predefined point without returning normally. It does not use a series of 
return statements. The setjmp function saves the context of the calling function 
in an environment buffer. 


#include <setjmp.h> 


int setimp (jmp_buf env): 


env 

The environment buffer, which must be an array of integers long enough to hold 
the register context of the calling function. The type jmp_buf is defined in the 
<setjmp.h> header file. The contents of the general-purpose registers, including 
the program counter (PC), are stored in the buffer. 


When set jmp is first called, it returns the value 0. If longjmp is then called, 
naming the same environment as the call to setjmp, control is returned to the 
setjmp call as if it had returned normally a second time. The return value of 
setjmp in this second return is the value supplied by you in the longjmp call. To 
preserve the true value of setjmp, the function calling setjmp must not be called 
again until the associated longjmp is called. 


The setjmp function preserves the hardware general-purpose registers, and the 
longjmp function restores them. After a longjmp, all variables have their values 
as of the time of the longjmp except for local automatic variables not marked 
volatile. These variables have indeterminate values. 


The setjmp and longjmp functions rely on the OpenVMS condition-handling 
facility to effect a nonlocal goto with a signal handler. The longjmp function 

is implemented by generating a HP C RTL specified signal that allows the 
OpenVMS condition-handling facility to unwind back to the desired destination. 


The HP C RTL must be in control of signal handling for any HP C image. 
For HP C to be in control of signal handling, you must establish all exception 
handlers through a call to the VAXCSESTABLISH function. See Section 4.2.5 and 
the VAXCSESTABLISH function for more information. 


Note 


The C RTL provides nonstandard decc$setjmp and decc$fast_longjmp 
functions for Alpha and 164 systems. To use these nonstandard functions 
instead of the standard ones, a program must be compiled with __FAST_ 
SETJMP or __UNIX_SETJMP macros defined. 


Unlike the standard longjmp function, the decc$fast_longjmp function 
does not convert its second argument from 0 to 1. After a call to 
decc$fast_longjmp, a corresponding setjmp function returns with the 
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Restrictions 


exact value of the second argument specified in the decc$fast_longjmp 
call. 


You cannot invoke the longjmp function from an OpenVMS condition handler. 
However, you may invoke longjmp from a signal handler that has been 
established for any signal supported by the HP C RTL, subject to the following 
nesting restrictions: 


Return Values 


The longjmp function will not work if you invoke it from nested signal 
handlers. The result of the longjmp function, when invoked from a signal 
handler that has been entered as a result of an exception generated in 
another signal handler, is undefined. 


Do not invoke the setjmp function from a signal handler unless the associated 
longjmp is to be issued before the handling of that signal is completed. 


Do not invoke the longjmp function from within an exit handler (established 
with atexit or SYS$DCLEXH). Exit handlers are invoked after image 
tear-down, so the destination address of the longjmp no longer exists. 


Invoking longjmp from within a signal handler to return to the main thread 
of execution might leave your program in an inconsistent state. Possible 
side effects include the inability to perform I/O or to receive any more UNIX 
signals. Use siglongjmp instead. 


See the Description section. 
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setkey 

Sets an encoding key for use by the encrypt function. 
Format 

#include <unistd.h> 

#include <stdlib.h> 

void setkey (const char *key;) 
Argument 

key 

A character array of length 64 containing 0s and 1s. 
Description 


The argument of setkey is a character array of length 64 containing only the 
characters with numerical value 0 and 1. If this string is divided into groups of 
8, the low-order bit in each group is ignored, leading to a 56-bit key which is set 
into the machine. 


No value is returned. 


See also crypt and encrypt. 
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setlocale 


Format 


Arguments 


Description 
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Selects the appropriate portion of the program’s locale as specified by the category 
and locale arguments. You can use this function to change or query one category 
or the program’s entire current locale. 


#include <locale.h> 


char *setlocale (int category, const char “locale); 


category 
The name of the category. Specify LC_ALL to change or query the entire locale. 
Other valid category names are: 


e LC_COLLATE 

e LC_CTYPE 

e LC_MESSAGES 
e LC_MONETARY 
e LC_NUMERIC 

e LC_TIME 


locale 
Pointer to a string that specifies the locale. 


The setlocale function sets or queries the appropriate portion of the program’s 
locale as specified by the category and locale arguments. Specifying LC_ALL for 
the category argument names the entire locale; specifying the other values name 
only a portion of the program’s locale. 


The /ocale argument points to a character string that identifies the locale to be 
used. This argument can be one of the following: 


e Name of the public locale 
Specifies the public locale in the following format: 
language_country.codeset [@modifier] 


The function searches for the public locale binary file in the location defined 
by the logical name SYS$I18N_LOCALE. The file type defaults to LOCALE. 
The period (.) and at-sign (@) characters in the name are replaced by an 
underscore (_). 


For example, if the specified name is "zh_CN.dechanzi@radical", the 
function searches for the SYS$118N_LOCALE:ZH CN _DECHANZI_ 
RADICAL.LOCALE binary locale file. 


e A file specification 


setiocale 


Specifies the binary locale file. It can be any valid file specification. If either 
the device or directory is omitted, the function first applies the current caller’s 
device and directory as defaults for any missing component. If the file is not 
found, the function applies the device and directory defined by the SYS$I18N_ 
LOCALE logical name as defaults. The file type defaults to .LOCALE. 


No wildcards are allowed. The binary locale file cannot reside on a remote 
node. 


"oO" 


Specifies the C locale. If a program does not call setlocale, the C locale is 
the default. 


"POSIX" 


This is the same as the C locale. 


me 


Specifies that the locale is initialized from the setting of the international 
environment logical names. The function checks the following logical names 
in the order shown until it finds a logical that is defined: 


1. LC_ALL 


2. Logical names corresponding to the category. For example, if LC_ 
NUMERIC is specified as the category, then the first logical name that 
setlocale checks is LC_NUMERIC. 


LANG 
4. SYS$LC_ALL 


The system default for the category, which is defined by the SYS$LC_* 
logical names. For example, the default for the LC_NUMERIC category is 
defined by the SYS$LC_NUMERIC logical name. 


6. SYS$LANG 


If none of the logical names is defined, the C locale is used as the default. 
The SYS$LC_* logical names are set up at the system startup time. 


Like the locale argument, the equivalence name of the international 
environment logical name can be either the name of the public locale or 

the file specification. The setlocale function treats this equivalence name as 
if it were specified as the locale argument. 


NULL 


Causes setlocale to query the current locale. The function returns a pointer 
to a string describing the portion of the program’s locale associated with 
category. Specifying the LC_ALL category returns the string describing the 
entire locale. The locale is not changed. 


The string returned from the previous call to setlocale 


Causes the function to restore the portion of the program’s locale associated 
with category. If the string contains the description of the entire locale, the 
part of the string corresponding to category is used. If the string describes 
the portion of the program’s locale for a single category, this locale is used. 
For example, this means that you can use the string returned from the call 
setlocale with the LC_COLLATE category to set the same locale for the 
LC_MESSAGES category. 
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Return Values 


If the specified locale is available, then setlocale returns a pointer to the 
string that describes the portion of the program’s locale associated with 
category. For the LC_ALL category, the returned string describes the entire 
program’s locale. If an error occurs, a NULL pointer is returned and the 
program’s locale is not changed. 


Subsequent calls to setlocale overwrite the returned string. If that part 
of the locale needs to be restored, the program should save the string. The 
calling program should make no assumptions about the format or length of 
the returned string. 


Pointer to a string describing the locale. 


NULL Indicates an error occurred; errno is set. 


Example 


#include <errno.h> 
#include <stdio.h> 
#include <locale.h> 


/* This program calls setlocale() three times. The second call */ 


/* is for a nonexistent locale. The third call is for an */ 
/* existing file that is not a locale file. */ 
main() 


{ 


char *ret_str; 


errno = 0; 
printf ("setlocale (LC_ALL, \"POSIX\")"); 
ret_str = (char *) setlocale(LC_ALL, "POSIX") ; 


if (ret_str == NULL) 
perror("setlocale error") ; 

else 
printf (" call was successful\n") ; 


errno = 0; 
printf("\n\nsetlocale (LC_ALL, \"junk.junk_codeset\")"); 
ret_str = (char *) setlocale(LC_ ALL, "junk.junk_codeset") ; 


if (ret_str == NULL) 
perror(" returned error") ; 
else 
printf (" call was successful\n") ; 


errno = 0; 
printf("\n\nsetlocale (LC_ALL, \"sys$login:login.com\")") ; 
ret_str = (char *) setlocale(LC_ALL, "sys$login:login.com") ; 


if (ret_str == NULL) 
perror(" returned error") ; 
else 
printf (" call was successful\n") ; 


} 


Running the example program produces the following result: 
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setlocale (LC_ALL, "POSIX") call was successful 


setlocale (LC_ALL, "junk.junk_codeset") 
returned error: no such file or directory 


setlocale (LC_ALL, "sys$login:login.com") 
returned error: nontranslatable vms error code: 0x35C07C 
$c-f-localebad, not a locale file 
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setpgid ipra, 164) 


Setpgid aipna, 164 


Format 


Arguments 


Description 


Sets the process group ID for job control. 


#include <unistd.h> 


int setpgid (pid_t pid, pid_t pgia); 


pid 
The process ID for which the process group ID is to be set. 


pgid 
The value to which the process group ID is set. 


The setpgid function is used either to join an existing process group or create a 
new process group within the session of the calling process. The process group ID 
of a session leader will not change. 


Upon successful completion, the process group ID of the process with a process 
ID of pid is set to pgid. As a special case, if pid is 0, the process ID of the calling 
process is used. Also, if pgid is 0, the process group ID of the indicated process is 
used. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 
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0 Successful completion. 


setpgid ipra, 164) 


—1 Indicates an error. The function sets errno to 
one of the following values: 


EACCES — The value of the pid argument 
matches the process ID of a child process 
of the calling process and the child process 
has successfully executed one of the exec 
functions. 


EINVAL — The value of the pgid argument 
is less than 0, or is not a value supported by 
the implementation. 


EPERM -— The process indicated by the pid 
argument is a session leader. The value of 
the pid argument matches the process ID 

of a child process of the calling process, and 
the child process is not in the same session 
as the calling process. The value of the pgid 
argument is valid but does not match the 
process ID of the process indicated by the 
pid argument, and there is no process with a 
process group ID that matches the value of 
the pgid argument in the same session as the 
calling process. 


ESRCH -— The value of the pid argument 
does not match the process ID of the calling 
process or of a child process of the calling 
process. 
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set pg r p (Alpha, I64) 


Format 


Description 


Sets the process group ID. 


#include <unistd.h> 


pid_t setpgrp (void); 


If the calling process is not already a session leader, setpgrp sets the process 
group ID of the calling process to the process ID of the calling process. If setpgrp 
creates a new session, then the new session has no controlling terminal. 


The setpgrp function has no effect when the calling process is a session leader. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Value 
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x The process group ID of the calling process. 


setpwent 


setpwent 

Rewinds the user database. 
Format 

#include <pwd.h> 

void setpwent (void); 
Description 


The setpwent function effectively rewinds the user database to allow repeated 
searches. 


No value is returned, but errno is set to EIO if an I/O error occurred. 


See also getpwent. 
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setregid apna, 1 


Format 


Arguments 


Description 


Sets the real and effective group IDs. 


#include <unistd.h> 


int setregid (gid_t rgid, gid_t egid); 


rgid 
The value to which you want the real group ID set. 


egid 
The value to which you want the effective group ID set. 


The setregid function is used to set the real and effective group IDs of the 
calling process. If rgid is —1, the real group ID is not changed; if egid is —1, the 
effective group ID is not changed. The real and effective group IDs can be set to 
different values in the same call. 


Only a process with the IMPERSONATE privilege can set the real group ID and 
the effective group ID to any valid value. 


A nonprivileged process can set either the real group ID to the saved set-group-ID 
from an exec function, or the effective group ID to the saved set-group-ID or the 
real group ID. 


Any supplementary group IDs of the calling process remain unchanged. 


If a set-group-ID process sets its effective group ID to its real group ID, it can 
still set its effective group ID back to the saved set-group-ID. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 
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0 Successful completion. 

—1 Indicates an error. Neither of the group IDs is 
changed, and errno is set to one of the following 
values: 


e EINVAL — The value of the rgid or egid 
argument is invalid or out-of-range. 


e EPERM - The process does not have the 
IMPERSONATE privilege, and a change 
other than changing the real group ID to the 
saved set-group-ID, or changing the effective 
group ID to the real group ID or the saved 
group ID, was requested. 


setreuid ipha, 164) 


setreuid (ipra, 164 


Format 


Arguments 


Description 


Sets the user IDs. 


#include <unistd.h> 


int setreuid (uid_t ruid, uid_t euia); 


ruid 
The value to which you want the real user ID set. 


euid 
The value to which you want the effective user ID set. 


The setreuid function sets the real and effective user IDs of the current process 
to the values specified by the ruid and euid arguments. If ruid or euid is —1, the 
corresponding effective or real user ID of the current process is left unchanged. 


A process with the IMPERSONATE privilege can set either ID to any value. An 
unprivileged process can set the effective user ID only if the ewid argument is 
equal to either the real, effective, or saved user ID of the process. 


It is unspecified whether a process without the IMPERSONATE privilege is 
permitted to change the real user ID to match the current real, effective, or saved 
user ID of the process. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 


0 Successful completion. 


—1 Indicates an error. The function sets errno to 
one of the following values: 


e EINVAL — The value of the ruid or euid 
argument is invalid or out of range. 


e EPERM - The current process does not have 
the IMPERSONATE privilege, and either an 
attempt was made to change the effective 
user ID to a value other than the real user 
ID or the saved set-user-ID, or an an attempt 
was made to change the real user ID to a 
value not permitted by the implementation. 
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Setsid ipra, 164 


Creates a session and sets the process group ID. 


Format 
#include <unistd.h> 
pid_t setsid (void); 


Description 


The setsid function creates a new session if the calling process is not a process 
group leader. Upon return, the calling process is the session leader of this new 
session and the process group leader of a new process group, and it has no 
controlling terminal. The process group ID of the calling process is set equal to 
the process ID of the calling process. The calling process is the only process in 
the new process group and the only process in the new session. 


This function requires that long (32-bit) UID/GID support be enabled. See 
Section 1.5.8 for more information. 


Return Values 


x The process group ID of the calling process. 


(pid_t)—1 Indicates an error. The function sets errno to the 
following value: 


e EPERM -— The calling process is already a 
process group leader, or the process group ID 
of a process other than the calling process 
matches the process ID of the calling process. 
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setstate 


Format 


Argument 


Description 


Restarts and changes random-number generators. 


char *setstate (char “state:) 


state 
Points to the array of state information. 


The setstate function handles restarting and changing random-number 
generators. 


Once you initialize a state, the setstate function allows rapid switching between 
state arrays. The array defined by state is used for further random-number 
generation until the initstate function is called or the setstate function is 
called again. The setstate function returns a pointer to the previous state array. 


After initialization, you can restart a state array at a different point in one of two 

ways: 

e Use the initstate function, with the desired seed, state array, and size of the 
array. 


e Use the setstate function, with the desired state, followed by the srandom 
function with the desired seed. The advantage of using both functions is that 
you do not have to save the state array size once you initialize it. 


See also initstate, srandom, and random. 


Return Values 


A pointer to the previous state array information. 


0 Indicates an error. The state information is 
damaged, and errno is set to the following value: 


e EINVAL—The state argument is invalid. 


REF-543 


setuid 


setuid 


Format 


Argument 


Description 


With POSIX IDs disabled, implemented for program portability and serves no 
function. It returns 0 (to indicate success). 


With POSIX IDs enabled, sets the user IDs. 


#include <types.h> 
#include <unistd.h> 
int setuid (__uid_t uid); (DECC_V4_SOURCE) 


uid_t setuid (uid_t uid); (mot .DECC_V4_SOURCE) 


uid 
The value to which you want the user IDs set. 


The setuid function can be used with POSIX style identifiers enabled or disabled. 


POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher. 


With POSIX IDs disabled (the default), the setuid function is implemented for 
program portability and serves no function. It returns 0 (to indicate success). 


With POSIX style IDs enabled: 


e Ifthe process has the IMPERSONATE privilege, the setuid function sets the 
real user ID, effective user ID, and the saved set-user-ID to wid. 


e Ifthe process does not have appropriate privileges but wid is equal to the real 
user ID or to the saved set-user-ID, then the setuid function sets the effective 


user ID to wid. The real user ID and saved set-user-ID remain unchanged. 
To enable/disable POSIX style IDs, see Section 1.7. 


Return Values 
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0 Successful completion. 
-1 Indicates an error. The function sets errno to 
one of the following values: 


e EINVAL -— The value of the uid argument 
is invalid and not supported by the 
implementation. 


e EPERM -— The process does not have 
appropriate privileges and wid does not 


match the real user ID or the saved set-user- 


ID. 


setvbuf 


setvbuf 


Format 


Arguments 


Description 


Associates a buffer with an input or output file and potentially modifies the 
buffering behavior. 


#include <stdio.h> 


int setvbuf (FILE *file_ptr, char *buffer, int type, size_t size); 


file_ptr 
A pointer to a file. 


buffer 
A pointer to a character array, or a NULL pointer. 


type 
The buffering type. Use one of the following values defined in <stdio.h>: _ 
IOFBF or _IOLBF. 


size 
The number of bytes to be used in buffer by the HP C RTL for buffering this file. 
The buffer size must be a minimum of 8192 bytes and a maximum of 32767 bytes. 


You can use the setvbuf function after the file is opened but before any I/O 
operations are performed. 


The C RTL provides the following types of ANSI-conforming file buffering: 


In line-buffered I/O, characters are buffered in an area of memory until a new- 
line character is seen, at which point the appropriate RMS routine is called to 
transmit the entire buffer. Line buffering is more efficient than unbuffered I/O 
since it reduces the system overhead, but it delays the availability of the data to 
the user or disk on output. 


In fully buffered I/O, characters are buffered in an area of memory until the 
buffer is full, regardless of the presence of break characters. Full buffering is 
more efficient than line buffering or unbuffered I/O, but it delays the availability 
of output data even longer than line buffering. 


Use the values JOLBF and _IOFBF defined in <stdio.h> for the type argument 
to specify line-buffered and fully buffered I/O, respectively. 


If file_ptr specifies a terminal device, the HP C RTL uses line-buffered I/O; 
otherwise, it uses fully buffered I/O. 


Please note that the previously documented value _IONBF is not supported. 


The HP C RTL automatically allocates a buffer to use for each I/O stream, so 
there are several buffer allocation possibilities: 


e If buffer is not a NULL pointer and size is not smaller than the automatically 
allocated buffer, then setvbuf uses buffer as the file buffer. 
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e If buffer is a NULL pointer or size is smaller than the automatically allocated 
buffer, the automatically allocated buffer is used as the buffer area. 


e If buffer is a NULL pointer and size is larger than the automatically allocated 
buffer, then setvbuf allocates a new buffer equal to the specified size and 
uses that as the file buffer. 


User programs must not depend on the contents of buffer once I/O has been 
performed on the stream. The HP C RTL might or might not use buffer for any 
given I/O operation. 


Generally, it is unnecessary to use setvbuf or setbuf to control the buffer size 
used by the HP C RTL. The automatically allocated buffer sizes are chosen 
for efficiency based on the kind of I/O operations performed and the device 
characteristics (such as terminal, disk, or socket). 


The setvbuf and setbuf functions are useful to introduce buffering for improved 
performance when writing a large amount of text to the stdout stream. This 
stream is unbuffered by default when bound to a terminal device (the normal 
case), and therefore incurs a large number of OpenVMS buffered I/O operations 
unless HP C RTL buffering is introduced by a call to setvbuf or setbuf. 


The setvbuf function is used only to control the buffering used by the HP C RTL, 
not the buffering used by the underlying RMS I/O operations. You can modify 
RMS default buffering behavior by specifying various values for the ctx, fop, rat, 
gbc, mbc, mbf, rfm, and rop RMS keywords when the file is opened by the creat, 
freopen or open functions. 


Return Values 
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0 Indicates success. 


nonzero value Indicates that an invalid input value was 
specifed for type or file_ptr, or because file_ptr is 
being used by another thread (see Section 1.9.1). 


shm_open (ipa, 164) 


SHM_OPeN Apia, 164) 


Format 


Argument 


Description 


Opens a shared memory object. 


#include <sys/mman.h> 


int shm_open (const char *name, int oflag, mode_t mode); 


name 
Pointer to a string naming a shared memory object. 


oflag 

Specifies options that define file status and file access modes. This argument is 
constructed from the bitwise inclusive OR of zero or more of the options defined 
in the <fcntl.h> header file. 


mode 
The shared memory object’s permission bits. This argument is used only when 
the shared memory object is being created. 


The shm_open function establishes a connection between a shared memory object 
and a file descriptor. It creates an open file description that refers to the shared 
memory object and a file descriptor that refers to that open file description. The 
file descriptor is used by other functions to refer to that shared memory object. 
The name argument points to a string naming a shared memory object. The 
name can be a pathname, in which case other processes referring to the same 
pathname refer to the same shared memory object. 


When a shared memory object is created, its state and all data associated with it 
persist until the shared memory is unlinked. 


The shm_open function returns a file descriptor for the shared memory object that 
is the lowest numbered file descriptor not currently open for that process. 


The file status flags and file access modes of the open file description are set 
according to the value of oflag, and can have zero or more of the following values: 


O_RDONLY -— Open for read access only. 
O_RDWR — Open for read or write access. 


O_CREAT — Create the shared memory if the memory object does not exist 
already. The user ID and group ID of the shared memory object are identical 
to those of the calling process. The shared memory object’s permission bits 
are set to the value of mode, except those set in the file mode creation mask 
of the process. 


O_EXCL — Prevent the opening of a shared memory object if O_CREAT is 
set and the shared memory object already exists. Use this option only in 
combination with O_CREAT. 
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O_TRUNC — Truncate the shared memory object to zero length if it is 
successfully opened for read or write access (O_RDWR). 


The initial contents of the shared memory object are binary zeros. 


Return Values 
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n 


Upon success, a nonnegative integer representing 
the lowest numbered unused file descriptor. 

The file descriptor points to the shared memory 
object. 


Indicates failure. errno is set to indicate the 
error: 


EACCES — Permission to create the shared 
memory object is denied, or the shared 
memory object exists and the permissions 
specified by oflag are denied, or O_TRUNC is 
specified and write permission is denied. 


EEXIST — O_CREAT and O_EXCL are set, 
but the named shared memory object already 
exists. 


EINTR — A signal has interrupted the 
shm_open operation. 


EINVAL — The shm_open operation is not 
supported for the given name. 


EMFILE — Too many file descriptors are 
currently in use by this process. 


ENAMETOOLONG - The length of the name 
argument exceeds PATH_MAX or a pathname 
component is longer than NAME_MAX. 


ENFILE — Too many shared memory objects 
are currently open in the system. 


ENOENT — O_CREAT is not set and the 
named shared memory object does not exist. 


ENOSPC — Memory space for creation of the 
new shared memory object is insufficient. 


shm_unlink dona, 164 


sh m_un LiNk (ipna, 164) 


Format 


Argument 


Description 


Removes a shared memory object. 


#include <sys/mman.h> 


int shm_unlink (const char *name); 


name 
Pointer to a string naming the shared memory object to remove. 


The shm_unlink function removes the name of the shared memory object named 
by the string pointed to by name. 


If one or more references to the shared memory object exist when the object is 
unlinked, the name is removed before shm_ unlink returns, but the removal of 
the memory object contents is postponed until all open and map references to the 
shared memory object have been removed. 


Even if the object continues to exist after the last shm_ unlink, reuse of the name 
subsequently causes shm_ unlink to behave as if no shared memory object with 
this name exists (that is, shm_open will fail if O_CREAT is not set, or will create 
a new shared memory object if O_CREAT is set). 


Return Values 


0 Indicates success. 


-1 Indicates failure, the named shared memory 
object is not changed by the function call, and 
errno is set to indicate the error: 


e EACCES — Permission is denied to unlink 
the named shared memory object. 


e ENAMETOOLONG -— The length of the name 
argument exceeds PATH_MAX or a pathname 
component is longer than NAME_MAX. 


e ENOENT - The named shared memory 
object does not exist. 
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sigaction 


Format 


Arguments 


Description 
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Specifies the action to take upon delivery of a signal. 


#include <signal.h> 


int sigaction (int sig, const struct sigaction “action, struct sigaction *o_action); 


sig 
The signal for which the action is to be taken. 
action 


A pointer to a sigaction structure that describes the action to take when you 
receive the signal specified by the sig argument. 


o_action 

A pointer to a sigaction structure. When the sigaction function returns from 
a call, the action previously attached to the specified signal is stored in this 
structure. 


When a process requests the sigaction function, the process can both examine 
and specify what action to perform when the specified signal is delivered. The 
arguments determine the behavior of the sigaction function as follows: 


e Specifying the sig argument identifies the affected signal. Use any one of the 
signal values defined in the <signal.h> header file, except SIGKILL. 
If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, then 
a SIGCHLD signal is generated for the calling process whenever any of its 
child processes stop. If sig is SIGCHLD and the SA_NOCLDSTOP flag is set 
in sa_flags, then SIGCHLD signal is not generated in this way. 


e Specifying the action argument, if not null, points to a sigaction structure 
that defines what action to perform when the signal is received. If the action 
argument is null, signal handling remains unchanged, so you can use the call 
to inquire about the current handling of the signal. 


e Specifying the o_action argument, if not null, points to a sigaction structure 
that contains the action previously attached to the specified signal. 


The sigaction structure consists of the following members: 


void (*sa_handler) (int) ; 
sigset_t sa_mask; 
int sa_ flags; 


The sigaction structure members are defined as follows: 


sigaction 


sa_handler This member can contain the following values: 


e SIG_DFL - Specifies the default action taken when the 
signal is delivered. 


e SIG_IGN — Specifies that the signal has no effect on the 
receiving process. 


e Function pointer — Requests to catch the signal. The signal 
causes the function call. 


sa_mask This member can request that individual signals, in addition 
to those in the process signal mask, are blocked from delivery 
while the signal handler function specified by the sa_handler 
member is executing. 


sa_flags This member can set the flags to enable further control over the 
actions taken when a signal is delivered. 
The sa_flags member of the sigaction structure has the following values: 


SA_ONSTACK Setting this bit causes the system to run the signal 
catching function on the signal stack specified by the 
sigstack function. If this bit is not set, the function 
runs on the stack of the process where the signal is 


delivered. 

SA_RESETHAND Setting this bit resets the signal to SIG_DFL. Be 
aware that you cannot automatically reset SIGILL 
and SIGTRAP. 

SA_NODEFER Setting this bit does not automatically block the signal 
as it is caught. 

SA_NOCLDSTOP If this bit is set and the sig argument is equal to 


SIGCHLD and a child process of the calling process 
stops, then a SIGCHLD signal is sent to the calling 
process only if SA.NOCLDSTOP is not set for 
SIGCHLD. 


When a signal is caught by a signal-catching function installed by sigaction, 

a new signal mask is calculated and installed for the duration of the signal- 
catching function (or until a call to either sigprocmask or sigsuspend is made. 
This mask is formed by taking the union of the current signal mask and the 
value of the sa_mask for the signal being delivered unless SA.NODEFER or SA_ 
RESETHAND is set, and then including the signal being delivered. If and when 
the user’s signal handler returns normally, the original signal mask is restored. 


Once an action is installed for a specific signal, it remains installed until another 
action is explicitly requested (by another call to sigaction), until the SA_ 
RESETHAND flag causes resetting of the handler, or until one of the exec 
functions is called. 


If the previous action for a specified signal had been established by signal, the 
values of the fields returned in the structure pointed to by the o_action argument 
of sigaction are unspecified, and in particular o_action->sa_handler is not 
necessarily the same value passed to signal. However, if a pointer to the same 
structure or a copy thereof is passed to a subsequent call to sigaction by means 
of the action argument of sigaction), the signal is handled as if the original call 
to signal were repeated. 


If sigaction fails, no new signal handler is installed. 


REF-551 


sigaction 


It is unspecified whether an attempt to set the action for a signal that cannot be 
caught or ignored to SIG_DFL is ignored or causes an error to be returned with 
errno set to EINVAL. 


See Section 4.2 for more information on signal handling. 


Note 


The sigvec and signal functions are provided for compatibility to old 
UNIX systems; their function is a subset of that available with the 
sigaction function. 


See also sigstack, sigvec, signal, wait, read, and write. 
Return Values 


0 Indicates success. 


-1 Indicates an error; A new signal handler is not 
installed. errno is set to one of the following 
values: 


e EFAULT - The action or o_action argument 
points to a location outside of the allocated 
address space of the process. 


e EINVAL - The sig argument is not a valid 
signal number. Or an attempt was made to 
ignore or supply a handler for the SIGKILL, 
SIGSTOP, and SIGCONT signals. 
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sigaddset 


Format 


Arguments 


Description 


Example 


Adds the specified individual signal. 


#include <signal.h> 


int sigaddset (sigset_t “set, int sig_number); 


set 
The signal set. 


sig_number 
The individual signal. 


The sigaddset function manipulates sets of signals. This function operates on 
data objects that you can address by the application, not on any set of signals 
known to the system. For example, this function does not operate on the set 
blocked from delivery to a process or the set pending for a process. 


The sigaddset function adds the individual signal specified by sig_number from 
the signal set specified by set. 


The following example shows how to generate and use a signal mask that blocks 
only the SIGINT signal from delivery: 


#include <signal.h> 
int return_value; 
sigset_t newset; 


sigemptyset (&newset) ; 
sigaddset (&newset, SIGINT) ; 
return_value = sigprocmask (SIG SETMASK, &newset, NULL) ; 


Return Values 


0 Indicates success. 


-1 Indicates an error; errno is set to the following 
value: 


e EINVAL - The value of sig_number is not a 
valid signal number. 
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sigblock 


sigblock 


Format 


Argument 


Description 


Adds the signals in mask to the current set of signals being blocked from delivery. 


#include <signal.h> 


int sigblock (int mask); 


mask 
The signals to be blocked. 


Signal i is blocked if the i — 1 bit in mask is a 1. For example, to add the 
protection-violation signal to the set of blocked signals, use the following line: 


sigblock(1 << (SIGBUS - 1)); 


You can express signals in mnemonics (such as SIGBUS for a protection violation) 
or numbers as defined in the <signal.h> header file, and you can express 
combinations of signals by using the bitwise OR operator ( | ). 


Return Value 
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x Indicates the previous set of masked signals. 


sigdelset 


sigdelset 


Format 


Arguments 


Description 


Deletes a specified individual signal. 


#include <signal.h> 


int sigdelset (sigset_t “set, int sig_number) 


set 
The signal set. 


sig_number 
The individual signal. 


The sigdelset function deletes the individual signal specified by sig_number 
from the signal set specified by set. 


This function operates on data objects that you can address by the application, 
not on any set of signals known to the system. For example, this function does 
not operate on the set blocked from delivery to a process or the set pending for a 
process. 


Return Values 


0 Indicates success. 
—1 Indicates an error; errno is set to the following 
value: 


e EINVAL -— The value of sig_number is not a 
valid signal number. 
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sigemptyset 


sigemptyset 


Initializes the signal set to exclude all signals. 


Format 
#include <signal.h> 
int sigemptyset (sigset_t *set); 

Argument 
set 
The signal set. 

Description 
The sigemptyset function initializes the signal set pointed to by set such that you 
exclude all signals. A call to sigemptyset or sigfillset must be made at least 
once for each object of type sigset_t prior to any other use of that object. 
This function operates on data objects that you can address by the application, 
not on any set of signals known to the system. For example, this function does 
not operate on the set blocked from delivery to a process or the set pending for a 
process. 
See also sigfillset. 

Example 


The following example shows how to generate and use a signal mask that blocks 
only the SIGINT signal from delivery: 


#include <signal.h> 
int return_value; 
sigset_t newset; 


sigemptyset (&newset) ; 


sigaddset (&newset, SIGINT) ; 
return_value = sigprocmask (SIG SETMASK, &newset, NULL) ; 


Return Values 


0 Indicates success. 


—1 Indicates an error; the global errno is set to 
indicate the error. 
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sigfillset 


sigfillset 


Format 


Argument 


Description 


Initializes the signal set to include all signals. 


#include <signal.h> 


int sigfillset (sigset_t *set); 


set 
The signal set. 


The sigfillset function initializes the signal set pointed to by set such that you 
include all signals. A call to sigemptyset or sigfillset must be made at least 
once for each object of type sigset_t prior to any other use of that object. 


This function operates on data objects that you can address by the application, 
not on any set of signals known to the system. For example, this function does 
not operate on the set blocked from delivery to a process or the set pending for a 
process. 


See also sigemptyset. 


Return Values 


0 Indicates success. 
—1 Indicates an error; errno is set to the following 
value: 


e EINVAL — The value of the sig_number 
argument is not a valid signal number. 
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sighold (Alpha, I64) 


Sighold sipia, 162 


Format 


Argument 


Description 


Adds the specified signal to the calling process’s signal mask. 


#include <signal.h> 


int sighold (int signa); 


signal 
The specified signal. The signal argument can be assigned any of the signals 
defined in the <signal.h> header file, except SIGKILL and SIGSTOP. 


The sighold, sigrelse, and sigignore functions provide simplified signal 
management: 


e The sighold function adds signal to the calling process’s signal mask. 
e The sigrelse function removes signal from the calling process’s signal mask. 
e The sigignore function sets the disposition of signal to SIG_IGN. 


The sighold function, in conjunction with sigrelse and sigpause, can be used 
to establish critical regions of code that require the delivery of a signal to be 
temporarily deferred. 


Upon success, the sighold function returns a value of 0. Otherwise, a value of 
—1 is returned, and errno is set to indicate the error. 


Note 


These interfaces are provided for compatibility only. New programs 
should use sigaction and sigprocmask to control the disposition of 
signals. 


Return Values 
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0 Indicates success. 


-1 Indicates an error; errno is set to the following 
value: 


e EINVAL — The value of the signal argument 
is either an invalid signal number or 
SIGKILL. 


Sigignore (pha, 164) 


SIgignOre (Aipra, 164 


Format 


Argument 


Description 


Sets the disposition of the specified signal to SIG_IGN. 


#include <signal.h> 


int sigignore (int signal); 


signal 
The specified signal. The signal argument can be assigned any of the signals 
defined in the <signal.h> header file, except SIGKILL and SIGSTOP. 


The sighold, sigrelse, and sigignore functions provide simplified signal 
management: 


e The sighold function adds signal to the calling process’s signal mask. 
e The sigrelse function removes signal from the calling process’s signal mask. 
e The sigignore function sets the disposition of signal to SIG_IGN. 


The sighold function, in conjunction with sigrelse and sigpause, can be used 
to establish critical regions of code that require the delivery of a signal to be 
temporarily deferred. 


Upon success, the sigignore function returns a value of 0. Otherwise, a value of 
—1 is returned, and errno is set to indicate the error. 


Note 


These interfaces are provided for compatibility only. New programs 
should use sigaction and sigprocmask to control the disposition of 
signals. 


Return Values 


0 Indicates success. 


—1 Indicates an error; errno is set to the following 
value: 


e EINVAL — The value of the signal argument 
is either an invalid signal number or 
SIGKILL, or an attempt is made to catch 
a signal that cannot be caught or to ignore a 
signal that cannot be ignored. 
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sigismember 


sigismember 


Tests whether a specified signal is a member of the signal set. 


Format 

#include <signal.h> 

int sigismember (const sigset_t *set, int sig_number); 
Arguments 

set 

The signal set. 

sig_number 

The individual signal. 
Description 


The sigismember function tests whether sig_number is a member of the signal set 
pointed to by set. 


This function operates on data objects that you can address by the application, 
not on any set of signals known to the system. For example, this function does 
not operate on the set blocked from delivery to a process or the set pending for a 
process. 


Return Values 


1 Indicates success. The specified signal is a 
member of the specified set. 


0 Indicates an error. The specified signal is not a 
member of the specified set. 
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siglongjmp 


siglongjmp 


Format 


Arguments 


Description 


Nonlocal goto with signal handling. 


#include <setjmp.h> 


void siglongjmp (sigijmp_buf env, int value); 


env 
An address for a sigjmp_ buf structure. 


value 
A nonzero value. 


The siglongjmp function restores the environment saved by the most recent call 
to sigsetjmp in the same process with the corresponding sigjmp buf argument. 


All accessible objects have values when siglongjmp is called, with one exception: 
values of objects of automatic storage duration that changed between the 
sigsetjmp call and siglongjmp call are indeterminate. 


Because it bypasses the usual function call and return mechanisms, siglongjmp 
executes correctly during interrupts, signals, and any of their associated 
functions. However, if you invoke siglongjmp from a nested signal handler 
(for example, from a function invoked as a result of a signal raised during the 
handling of another signal), the behavior is undefined. 


The siglongjmp function restores the saved signal mask only if you initialize the 
env argument by a call to sigsetjmp with a nonzero savemask argument. 


After siglongjmp is completed, program execution continues as if the 
corresponding call of sigsetjmp just returned the value specified by value. 

The siglongjmp function cannot cause sigsetjmp to return 0 (zero); if value is 0, 
sigsetjmp returns 1 


See also sigsetjmp. 
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sigmask 


sigmask 

Constructs the mask for a given signal number. 
Format 

#include <signal.h> 

int sigmask (signum); 
Argument 


signum 
The signal number for which the mask is to be constructed. 


Description 


The sigmask function is used to contruct the mask for a given signum. This mask 
can be used with the sigblock function. 


Return Value 


x The mask constructed for signum 
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signal 


signal 


Format 


Arguments 


Description 


Allows you to specify the way in which the signal sig is to be handled: use the 
default handling for the signal, ignore the signal, or call the signal handler at the 
address specified. 


#include <signal.h> 


void (‘signal (int sig, void (*func) (int))) (int); 


sig 
The number or mnemonic associated with a signal. This argument is usually one 
of the mnemonics defined in the <signal.h> header file. 


func 
Either the action to take when the signal is raised, or the address of a function 
needed to handle the signal. 


If func is the constant SIG_DFL, the action for the given signal is reset to the 
default action, which is to terminate the receiving process. If the argument is 
SIG_IGN, the signal is ignored. Not all signals can be ignored. 


If func is neither SIG_DFL nor SIG_IGN, it specifies the address of a signal- 
handling function. When the signal is raised, the addressed function is called 
with sig as its argument. When the addressed function returns, the interrupted 
process continues at the point of interruption. (This is called catching a 
signal. Signals are reset to SIG_DFL after they are caught, except as shown 
in Chapter 4.) 


You must call the signal function each time you want to catch a signal. 
See Section 4.2 for more information on signal handling. 


To cause an OpenVMS exception or a signal to generate a UNIX style signal, 
OpenVMS condition handlers must return SS$_RESIGNAL upon receiving 

any exception that they do not want to handle. Returning SS$_ CONTINUE 
prevents the correct generation of a UNIX style signal. See Chapter 4 for a list of 
OpenVMS exceptions that correspond to UNIX signals. 


Return Values 


x The address of the function previously 
established to handle the signal. 
SIG_ERR Indicates that the sig argument is out of range. 
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sigpause 


sigpause 

Assigns mask to the current set of masked signals and then waits for a signal. 
Format 

#include <signal.h> 

int sigpause (int mask); 
Argument 


mask 
The signals to be blocked. 


Description 
See the sigblock function for information about the mask argument. 


When control returns to sigpause, the function restores the previous set of 
masked signals, sets errno to EINTR, and returns —1 to indicate an interrupt. 
The value EINTR is defined in the <errno.h> header file. 


Return Value 


—1 Indicates an interrupt. errno is set to EINTR. 
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sigpending 


sigpending 
Examines pending signals. 


Format 
#include <signal.h> 


int sigpending (sigset_t *set); 


Argument 


set 
A pointer to a sigset_t structure. 


Description 


The sigpending function stores the set of signals that are blocked from delivery 
and pending to the calling process in the location pointed to by the set argument. 


Call either the sigemptyset or the sigfillset function at least once for each 
object of type sigset_t prior to any other use of that object. If you do not 
initialize an object in this way and supply an argument to the sigpending 
function, the result is undefined. 


See also sigemptyset and sigfillset in this section. 


Return Values 


0 Indicates success. 


—1 Indicates an error; errno is set to the following 
value: 


e SIGSEGV — Bad mask argument. 


REF-565 


sigprocmask 


sigprocmask 


Format 


Arguments 


Description 
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Sets the current signal mask. 


#include <signal.h> 


int sigorocmask (int how, const sigset_t “set, sigset_t *o_set); 


how 
An integer value that indicates how to change the set of masked signals. Use one 
of the following values: 


SIG_BLOCK The resulting set is the union of the current set and the 
signal set pointed to by the set argument. 

SIG_UNBLOCK The resulting set is the intersection of the current set 
and the complement of the signal set pointed to by the set 
argument. 

SIG_SETMASK The resulting set is the signal set pointed to by the set 
argument. 

set 


The signal set. If the value of the set argument is: 


e Not NULL - It points to a set of signals used to change the currently blocked 
set. 


e NULL — The value of the how argument is not significant, and the process 
signal mask is unchanged, so you can use the call to inquire about currently 
blocked signals. 


o_set 
A non-NULL pointer to the location where the signal mask in effect at the time 
of the call is stored. 


The sigprocmask function is used to examine or change the signal mask of the 
calling process. 


Typically, use the sigprocmask SIG_BLOCK value to block signals during a 
critical section of code, then use the sigprocmask SIG_SETMASK value to restore 
the mask to the previous value returned by the sigprocmask SIG_BLOCK value. 


If there are any unblocked signals pending after the call to the sigprocmask 
function, at least one of those signals is delivered before the sigprocmask function 
returns. 


You cannot block SIGKILL or SIGSTOP signals with the sigprocmask function. If 
a program attempts to block one of these signals, the sigprocmask function gives 
no indication of the error. 


Example 


sigprocmask 


The following example shows how to set the signal mask to block only the SIGINT 
signal from delivery: 


Return Values 


#include <signal.h> 
int return_value; 
sigset_t newset; 


sigemptyset (&newset) ; 
sigaddset (&newset, SIGINT) ; 
return_value = sigprocmask (SIG SETMASK, &newset, NULL) ; 


Indicates success. 


Indicates an error. The signal mask of the 
process is unchanged. errno is set to one of the 
following values: 


e EINVAL -— The value of the how argument is 
not equal to one of the defined values. 


e EFAULT - The set or o_set argument points 
to a location outside the allocated address 
space of the process. 
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sigrelse (Alpha, 164) 


sig relse (Alpha, 164) 


Format 


Argument 


Description 


Removes the specified signal from the calling process’s signal mask. 


#include <signal.h> 


int sigrelse (int signal; 


signal 
The specified signal. The signal argument can be assigned any of the signals 
defined in the <signal.h> header file, except SIGKILL and SIGSTOP. 


The sighold, sigrelse, and sigignore functions provide simplified signal 
management: 


e The sighold function adds signal to the calling process’s signal mask. 
e The sigrelse function removes signal from the calling process’s signal mask. 
e The sigignore function sets the disposition of signal to SIG_IGN. 


The sighold function, in conjunction with sigrelse and sigpause, can be used 
to establish critical regions of code that require the delivery of a signal to be 
temporarily deferred. 


Upon success, the sigrelse function returns a value of 0. Otherwise, a value of 
—1 is returned, and errno is set to indicate the error. 


Note 


These interfaces are provided for compatibility only. New programs 
should use sigaction and sigprocmask to control the disposition of 
signals. 


Return Values 
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0 Indicates success. 


-1 Indicates an error; errno is set to the following 
value: 


e EINVAL - The value of the signal argument 
is either an invalid signal number or 
SIGKILL. 


sigsetjmp 


sigsetjmp 
Sets a jump point for a nonlocal goto. 


Format 
#include <setjmp.h> 


init sigsetimp (sigjmp_buf env, int savemask): 


Arguments 


env 
An address for a sigjmp_ buf structure. 


savemask 
An integer value that specifies whether you need to save the current signal mask. 


Description 


The sigsetjmp function saves its calling environment in its env argument for 
later use by the siglongjmp function. 


If the value of savemask is not 0 (zero), sigsetjmp also saves the process’s current 
signal mask as part of the calling environment. 


See also siglongjmp. 


Restrictions 


You cannot invoke the longjmp function from an OpenVMS condition handler. 
However, you may invoke longjmp from a signal handler that has been 
established for any signal supported by the HP C RTL, subject to the following 
nesting restrictions: 


e The longjmp function will not work if you invoke it from nested signal 
handlers. The result of the longjmp function, when invoked from a signal 
handler that has been entered as a result of an exception generated in 
another signal handler, is undefined. 


e Do not invoke the sigsetjmp function from a signal handler unless the 
associated long jmp is to be issued before the handling of that signal is 
completed. 


e Do not invoke the longjmp function from within an exit handler (established 
with atexit or SYS$DCLEXH). Exit handlers are invoked after image 
tear-down, so the destination address of the longjmp no longer exists. 


e Invoking longjmp from within a signal handler to return to the main thread 
of execution might leave your program in an inconsistent state. Possible 
side effects include the inability to perform I/O or to receive any more UNIX 
signals. Use siglongjmp instead. 
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sigsetjmp 


Return Values 


0 Indicates success. 
nonzero The return is a call to the siglongjmp function. 
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sigsetmask 


sigsetmask 


Establishes those signals that are blocked from delivery. 


Format 
#include <signal.h> 


int sigsetmask (int mask); 


Argument 


mask 
The signals to be blocked. 


Description 


See the sigblock function for information about the mask argument. 
Return Value 


x The previous set of masked signals. 
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sigstack (vax oniy) 


sigstack wax ony) 


Format 


Arguments 


Description 


Defines an alternate stack on which to process signals. This allows the processing 
of signals in a separate environment from that of the current process. This 
function is nonreentrant. 


#include <signal.h> 


int sigstack (struct sigstack *ss, struct sigstack *oss); 


ss 

If ss is not NULL, it specifies the address of a structure that holds a pointer to 
a designated section of memory to be used as a signal stack on which to deliver 
signals. 


oss 
If oss is not NULL, it specifies the address of a structure in which the old value 
of the stack address is returned. 


The sigstack structure is defined in the <signal.h> standard header file: 


struct sigstack 


char *SS_SD; 
int ss_onstack; 
1 

If the sigvec function specifies that the signal handler is to execute on the signal 
stack, the system checks to see if the process is currently executing on that stack. 
If the process is not executing on the signal stack, the system arranges a switch 
to the signal stack for the duration of the signal handler’s execution. If the oss 
argument is not NULL, the current state of the signal stack is returned. 


Signal stacks must be allocated an adequate amount of storage; they do not 
expand like the run-time stack. For example, if your signal handler calls printf 
or any similarly complex HP C RTL routine, at least 12,000 bytes of storage 
should be allocated for the signal stack. If the stack overflows, an error occurs. 


ss_sp must point to at least four bytes before the end of the allocated memory 
area (see the example). This is architecture-dependent and possibly not portable 
to other machine architectures or operating systems. 


Return Values 
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0 Indicates success. 
—1 Indicates failure. 


sigstack (vax oni) 


Example 


#define ss_ size 15000 
static char mystack[ss_ size]; 
struct sigstack ss = {&mystack + sizeof(mystack) - sizeof(void *), 1}; 
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sigsuspend 


sigsuspend 


Format 


Argument 


Description 
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Atomically changes the set of blocked signals and waits for a signal. 


#include <signal.h> 


int sigsuspend (const sigset_t *signal_mask); 


signal_mask 
A pointer to a set of signals. 


The sigsuspend function replaces the signal mask of the process with the set of 
signals pointed to by the signal_mask argument. Then it suspends execution of 
the process until delivery of a signal whose action is either to execute a signal 
catching function or to terminate the process. You cannot block the SIGKILL or 
SIGSTOP signals with the sigsuspend function. If a program attempts to block 
either of these signals, sigsuspend gives no indication of the error. 


If delivery of a signal causes the process to terminate, sigsuspend does not 
return. If delivery of a signal causes a signal catching function to execute, 
sigsuspend returns after the signal catching function returns, with the signal 
mask restored to the set that existed prior to the call to sigsuspend. 


The sigsuspend function sets the signal mask and waits for an unblocked signal 
as one atomic operation. This means that signals cannot occur between the 
operations of setting the mask and waiting for a signal. If a program invokes 
sigprocmask SIG_SETMASK and sigsuspend separately, a signal that occurs 
between these functions is often not noticed by sigsuspend. 


In normal usage, a signal is blocked by using the sigprocmask function at the 
beginning of a critical section. The process then determines whether there is 
work for it to do. If there is no work, the process waits for work by calling 
sigsuspend with the mask previously returned by sigprocmask. 


If a signal is caught by the calling process and control is returned from the signal 
handler, the calling process resumes execution after sigsuspend, which always 
returns a value of —1 and sets errno to EINTR. 


See also sigpause and sigprocmask. 


sigtimedwait (ipia, 164 


sigtimedwait (ipia, 164 


Suspends a calling thread and waits for queued signals to arrive. 


Format 
#include <signal.h> 


int sigtimedwait (const sigset_t set, siginfo_t *info, const struct timespec *timeout); 


Arguments 


set 
The set of signals to wait for. 


info 
Pointer to a siginfo structure that is receiving data describing the signal, 
including any application-defined data specified when the signal was posted. 


timeout 
A timeout for the wait. If timeout is NULL, the argument is ignored. 


Description 


The sigtimedwait function behaves the same as the sigwaitinfo function except 
that if none of the signals specified by set are pending, sigtimedwait waits for 
the time interval specified in the timespec structure referenced by timeout. If the 
timespec structure pointed to by timeout is zero-valued and if none of the signals 
specified by set are pending, then sigtimedwait returns immediately with an 
error. 


See also sigwait and sigwaitinfo. 


See Section 4.2 for more information on signal handling. 


Return Values 


x Upon successful completion, the signal number 
selected is returned. 

—1 Indicates that an error occurred; errno is set to 
one of the following values: 


e EINVAL — The timeout argument specified a 
tv_nsec value less than 0 or greater than or 
equal to 1 billion. 


e EINTR — The wait was interrupted by an 
unblocked, caught signal. 


e EAGAIN — No signal specified by set was 
generated within the specified timeout 
period. 
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sigvec 


sigvec 


Format 


Arguments 


Description 


Permanently assigns a handler for a specific signal. 


#include <signal.h> 


int sigvec (int sigint, struct sigvec “sv, struct sigvec “osv); 


sigint 
The signal identifier. 


SV 
Pointer to a sigvec structure (see the Description section). 


OsvV 
If osv is not NULL, the previous handling information for the signal is returned. 


If sv is not NULL, it specifies the address of a structure containing a pointer to 
a handler routine and mask to be used when delivering the specified signal, and 
a flag indicating whether the signal is to be processed on an alternative stack. If 
su—>onstack has a value of 1, the system delivers the signal to the process on a 
signal stack specified with sigstack. 


The sigvec function establishes a handler that remains established until 
explicitly removed or until the image terminates. 


The sigvec structure is defined in the <signal.h> header file: 


struct sigvec 


int (*handler) (); 
int mask; 
int  onstack; 


ti 


See Section 4.2 for more information on signal handling. 


Return Values 
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0 Indicates that the call succeeded. 
—1 Indicates that an error occurred. 


sSigwait (ipha, 164) 


Sigwait (aipia, 162 


Format 


Arguments 


Description 


Suspends a calling thread and waits for queued signals to arrive. 


#include <signal.h> 


int sigwait (const sigset_t set, int *sig); 


set 
The set of signals to wait for. 


sig 
Returns the signal number of the selected signal. 


The sigwait function suspends the calling thread until at least one of the signals 
in the set argument is in the caller’s set of pending signals. When this happens, 
one of those signals is automatically selected and removed from the set of pending 
signals. The signal number identifying that signal is then returned in the location 
referenced by sig. 


The effect is unspecified if any signals in the set argument are not blocked when 
the sigwait function is called. 


The set argument is created using the set manipulation functions sigemptyset, 
sigfillset, sigaddset, and sigdelset. 


If, while the sigwait function is waiting, a signal occurs that is eligible for 
delivery (that is, not blocked by the signal mask), that signal is handled 
asynchronously and the wait is interrupted. 


See also sigtimedwait and sigwaitinfo. 


See Section 4.2 for more information on signal handling. 


Return Values 


0 Upon successful completion, sigwait stores 
the signal number of the received signal at the 
location referenced by sig and returns 0. 


nonzero Indicates that an error occurred; errno is set to 
the following value: 


e EINVAL — The set argument contains an 
invalid or unsupported signal number. 
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sigwaitinfo (ipa, 164 


Sigwaitinfo (aipra, 162 


Suspends a calling thread and waits for queued signals to arrive. 


Format 
#include <signal.h> 


int sigwaitinfo (const sigset_t set, siginfo_t *info); 


Arguments 


set 
The set of signals to wait for. 


info 
Pointer to a siginfo structure that is receiving data describing the signal, 
including any application-defined data specified when the signal was posted. 


Description 


The sigwaitinfo function behaves the same as the sigwait function if the info 
argument is NULL. 


If the info argument is non-NULL, the sigwaitinfo function behaves the same 
as sigwait, except that the selected signal number is stored in the si_signo 
member of the siginfo structure, and the cause of the signal is stored in the 
si_code member. If any value is queued to the selected signal, the first such 
queued value is dequeued and the value is stored in the si_value member of info. 
The system resource used to queue the signal is released and made available to 
queue other signals. If no value is queued, the content of the si_value member 
is undefined. If no further signals are queued for the selected signal, the pending 
indication for that signal is reset. 


See also sigtimedwait and sigwait. 


See Section 4.2 for more information on signal handling. 
Return Values 


x Upon successful completion, the signal number 
selected is returned. 


—1 Indicates that an error occurred; errno is set to 
one of the following values: 


e EINVAL — The set argument contains an 
invalid or unsupported signal number. 


e EINTR — The wait was interrupted by an 
unblocked, caught signal. 
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sin 


sin 


Format 


Argument 


Description 


Returns the sine of its radian argument. 


#include <math.h> 

double sin (double x); 

float sinf (float x); (Alpha, 164) 

long double sin! (long double x); (Alpha, 164) 
double sind (double x); (Alpha, 164) 

float sindf (float x); (Aipha, 164) 


long double sindl (long double x); (Aipha, 164) 


x 
A radian expressed as a floating-point number. 


The sin functions compute the sine of x measured in radians. 


The sind functions compute the sine of x measured in degrees. 


Return Values 


x The sine of the argument. 
NaN x = +Infinity or NaN; errno is set to EDOM. 
0 Undeflow occurred; errno is set to ERANGE. 
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sinh 


sinh 

Returns the hyperbolic sine of its argument. 
Format 

#include <math.h> 

double sinh (double x); 

float sinhf (float x); (Alpha, 164) 

long double sinhl (long double x); (Alpha, 164) 
Argument 


x 
A real number. 


Return Values 


n The hyperbolic sine of the argument. 
HUGE_VAL Overflow occurred; errno is set to ERANGE. 
0 Underflow occurred; errno is set to ERANGE. 
NaN x is NaN; errno is set to EDOM. 
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sleep 


sleep 


Format 


Argument 


Description 


Suspends the execution of the current process (or thread in a threaded program) 
for at least the number of seconds indicated by its argument. 


#include <unistd.h> 
unsigned int sleep (unsigned seconds); (DECC_V4_SOURCE) 


int sleep (unsigned seconds); (not .DECC_V4_SOURCE) 


seconds 
The number of seconds. 


The sleep function sleeps for the specified number of seconds, or until a signal is 
received, or until the process (or thread in a threaded program) executes a call to 
SYS$WAKE. 


If a SIGALRM signal is generated, but blocked or ignored, the sleep function 
returns. For all other signals, a blocked or ignored signal does not cause sleep to 
return. 


Return Values 


x The number of seconds that the process awoke 
early. 
0 If the process slept the full number of seconds 


specified by seconds. 
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snprintf 


snprintf 


Format 


Arguments 


Description 
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Performs formatted output to a string in memory. 


#include <stdio.h> 


int snprintf (char “str, size_t n, const char “format_spec, ... ); 


str 
The address of the string that will receive the formatted output. 


n 
The size of the buffer referred to by str. 


format_spec 
A pointer to a character string that contains the format specification. For more 
information about format specifications and conversion characters, see Chapter 2. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, you may omit the output sources. 
Otherwise, the function calls must have at least as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Excess output pointers, if any, are ignored. 


The snprintf function is identical to the sprintf function with the addition of 
the n argument, which specifies the size of the buffer referred to by str. 


On successful completion, snprintf returns the number of bytes (excluding the 
terminating null byte) that would be written to str ifn is sufficiently large. 


If n is 0, nothing is written, the number of bytes (excluding the terminating null) 
that would be written if n were sufficiently large are returned, and str might be a 
NULL pointer. Otherwise, output bytes beyond the n — 1st are discarded instead 
of being written to the array, and a null byte is written at the end of the bytes 
actually written into the array. 


If an output error is encountered, a negative value is returned. 


For a complete description of the format specification and the output source, see 
Chapter 2. 


Return Values 


Negative value 


snprintf 


The number of bytes (excluding the terminating 
null byte) that would be written to str if n is 
sufficiently large. 


Indicates an output error occurred. The function 
sets errno. For a list of errno values set by this 
function, see fprintf. 
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sprintf 


Format 


Arguments 


Description 
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Performs formatted output to a string in memory. 


#include <stdio.h> 


int sprintf. (char “str, const char *format_spec, .. . ); 


str 
The address of the string that will receive the formatted output. It is assumed 
that this string is large enough to hold the output. 


format_spec 
A pointer to a character string that contains the format specification. For more 
information about format specifications and conversion characters, see Chapter 2. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, you may omit the output sources. 
Otherwise, the function calls must have at least as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Excess output pointers, if any, are ignored. 


The sprintf function places output followed by the null character (\0) in 
consecutive bytes starting at *str. The user must ensure that enough space is 
available. 


Consider the following example of a conversion specification: 
#include <stdio.h> 


main () 


int temp = 4, temp2 = 17; 
char s[80]; 


sprintf(s, "The answers are %d, and %d.", temp, temp2); 


In this example, character string s has the following contents: 
The answers are 4, and 17. 


For a complete description of the format specification and the output source, see 
Chapter 2. 


Return Values 


Negative value 


sprintf 


The number of characters placed in the output 
string, not including the final null character. 
Indicates an output error occurred. The function 
sets errno. For a list of errno values set by this 
function, see fprintf. 
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sqrt 

Returns the square root of its argument. 
Format 

#include <math.h> 

double sqrt (double x): 

float sqrtf (float x); (Alpha, 164) 

long double sqrtl (long double x); (Alpha, 164) 
Argument 


x 
A real number. 


Return Values 


val The square root of x, if x is nonnegative. 
0 x is negative; errno is set to EDOM. 
NaN x is NaN; errno is set to EDOM. 
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srand 


srand 


Format 


Argument 


Description 


Initializes the pseudorandom-number generator rand. 


#include <stdlib.h> 


void srand (unsigned int seed); 


seed 
An unsigned integer. 


The srand function uses the argument as a seed for a new sequence of 
pseudorandom numbers to be returned by subsequent calls to rand. 


If srand is then called with the same seed value, the sequence of pseudorandom 
numbers is repeated. 


If rand is called before any calls to srand, the same sequence of pseudorandom 
numbers is generated as when srand is first called with a seed value of 1. 
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srand48 


Format 


Argument 


Description 
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Initializes a 48-bit random-number generator. 


#include <stdlib.h> 


void srand48 (long int seed_val) 


seed_val 
The initialization value to begin randomization. Changing this value changes the 
randomization pattern. 


The srand48 function initializes the random-number generator. You can use 
this function in your program before calling the drand48, lrand48, or mrand48 
functions. (Although it is not recommended practice, constant default initializer 
values are automatically supplied if you call drand48, lrand48, or mrand48 
without calling an initialization function). 


The function works by generating a sequence of 48-bit integer values, Xz, 
according to the linear congruential formula: 


Xn+1 = (aXn+c)mod m n-s=-0 


The argument m equals 248, so 48-bit integer arithmetic is performed. Unless you 
invoke the 1cong48 function, the multiplier value a and the addend value c are: 


a 
Cc 


5DEECE66D16 = 2736731631558 
B16 = 138 


The initializer function srand48 sets the high-order 32 bits of Xi to the low-order 
32 bits contained in its argument. The low-order 16 bits of Xi are set to the 
arbitrary value 330E 4g. 


See also drand48, lrand48, and mrand48. 


srandom 


srandom 


Format 


Argument 


Description 


Initializes the pseudorandom-number generator random. 


#include <stdlib.h> 


int srandom (unsigned seed); 


seed 
An initial seed value. 


The srandom function uses the argument as a seed for a new sequence of 
pseudorandom numbers to be returned by subsequent calls to random. This 
function has virtually the same calling sequence and initialization properties as 
the srand function, but produce sequences that are more random. 


The srandom function initializes the current state with the initial seed value. The 
srandom function, unlike the srand function, does not return the old seed because 
the amount of state information used is more than a single word. 


See also rand, srand, random, setstate, and initstate. 


Return Values 


0 Indicates success. Initializes the state seed. 
-1 Indicates an error, further specified in the global 
errno. 
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sscanf 


Format 


Arguments 


Description 
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Reads input from a character string in memory, interpreting it according to the 
format specification. 


#include <stdio.h> 


int sscanf (const char “str, const char *format_spec, . . . ); 


str 
The address of the character string that provides the input text to sscanf. 


format_spec 
A pointer to a character string that contains the format specification. For more 
information about format specifications and conversion characters, see Chapter 2. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, you can omit the input pointers. 
Otherwise, the function calls must have at least as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


The following is an example of a conversion specification: 
main () 


char str[] = "4 17"; 
int temp, 
temp2 ; 


sscanf(str, "%d $d", &temp, &temp2) ; 
printf ("The answers are %d and %d.", temp, temp2); 


This example produces the following output: 


S RUN EXAMPLE 
The answers are 4 and 17. 


For a complete description of the format specification and the input pointers, see 
Chapter 2. 


Return Values 


EOF 


sscanf 


The number of successfully matched and 
assigned input items. 

Indicates that a read error occurred before any 
conversion. The function sets errno. For a list of 
the values set by this function, see fscanf. 
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ssignal 


Format 


Arguments 


Description 


Allows you to specify the action to take when a particular signal is raised. 


#include <signal.h> 


void (*ssignal (int sig, void (*func) (int, ... ))) (int, ... ); 


sig 
A number or mnemonic associated with a signal. The symbolic constants for 
signal values are defined in the <signal.h> header file (see Chapter 4). 


func 
The action to take when the signal is raised, or the address of a function that is 
executed when the signal is raised. 


The ssignal function is equivalent to the signal function except for the return 
value on error conditions. 


Since the signal function is defined by the ANSI C standard and the ssignal 
function is not, use signal for greater portability. 


See Section 4.2 for more information on signal handling. 


Return Values 
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x The address of the function previously 
established as the action for the signal. The 
address may be the value SIG_DFL (0) or 
SIG_IGN (1). 


0 Indicates errors. For this reason, there is no way 
to know whether a return status of 0 indicates 
failure, or whether it indicates that a previous 
action was SIG_DFL (0). 


[w]standend 


[w]standend 


Deactivate the boldface attribute for the specified window. The standend function 
operates on the stdscr window. 


Format 

#include <curses.h> 

int standend (void): 

int wstandend (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Description 


The standend and wstandend functions are equivalent to clrattr and wclrattr 
called with the attribute _BOLD. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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[w]standout 


Activate the boldface attribute of the specified window. The standout function 
acts on the stdscr window. 


Format 

#include <curses.h> 

int standout (void); 

int wstandout (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Description 


The standout and wstandout functions are equivalent to setattr and wsetattr 
called with the attribute _BOLD. 


Return Values 


OK Indicates success. 
ERR Indicates an error. 
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stat 


Format 


Accesses information about the specified file. 


#include <stat.h> 
int stat (const char “file_spec, struct stat *buffer); so POSIX-1) 


int stat (const char *file_spec, struct stat “buffer, ...); (HP C Extension) 


Function Variants 


Arguments 


Description 


Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the stat function that is 
equivalent to the behavior before OpenVMS Version 7.0. 


Compiling with the USE_STD_STAT feature-test macro defined enables a 
variant of the stat function that uses an X/Open standard-compliant definition 
of the stat structure. The USE_STD_STAT feature-test macro is mutually 
exclusive with the DECC_V4_SOURCE and _VMS_V6_SOURCE macros. 


file_spec 

A valid OpenVMS or UNIX style file specification (no wildcards). Read, write, 
or execute permission of the named file is not required, but you must be able to 
reach all directories listed in the file specification leading to the file. For more 
information about UNIX style file specifications, see Chapter 1. 


buffer 
A pointer to a structure of type stat. For convenience, a typedef stat_t is 
defined as struct stat in the <stat.h> header file. 


This argument receives information about the particular file. The members of the 
structure pointed to by buffer are described in the Description section. 


An optional default file-name string. 


This is the only optional RMS keyword that can be specified for the stat function. 
See the description of the creat function for the full list of optional RMS 
keywords and their values. 


When the _USE_STD_STAT feature-test macro is not enabled, the legacy stat 
structure is used. When _USE_STD_STAT is enabled, the X/Open standard- 
compliant stat structure is used. 
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Legacy stat Structure 


With the _USE_STD_STAT feature-test macro defined to DISABLE, the following 
legacy stat structure is used: 


Member Type Definition 

st_dev dev_t Pointer to the physical device name 
st_ino[3] ino _t Three words to receive the file ID 
st_mode mode t File “mode” (prot, dir, ... ) 

st_nlink nlink t For UNIX system compatibility only 
st_uid uid t Owner user ID 

st_gid gid t Group member: from st_uid 

st_rdev dev_t UNIX system compatibility — always 0 
st_size off t File size, in bytes. For st_size to 


report a correct value, you need to 
flush both the C RTL and RMS buffers. 


st_atime time t File access time; always the same as 
st_mtime 

st_mtime time t Last modification time 

st_ctime time t File creation time 

st_fab rfm char Record format 

st_fab rat char Record attributes 

st_fab fsz char Fixed header size 

st fab mrs unsigned Record size 


The types dev_t, ino t, off _t, mode t, nlink t, uid_t, gid_t, and time t, are 
defined in the <stat.h> header file. However, when compiling for compatibility 
(/DEFINE=_DECC_V4_SOURCE), only dev_t, ino t, and off _t are defined. 


The off _t data type is either a 32-bit or 64-bit integer. The 64-bit interface 
allows for file sizes greater than 2 GB, and can be selected at compile time by 
defining the LLARGEFILE feature-test macro as follows: 


CC/DEFINE= LARGEFILE 


As of OpenVMS Version 7.0, times are given in seconds since the Epoch (00:00:00 
GMT, January 1, 1970). 


The st_mode structure member is the status information mode defined in the 
<stat.h> header file. The st_mode bits are described as follows: 


Bits Constant Definition 

0170000 S_IFMT Type of file 

0040000 S_IFDIR Directory 

0020000 S_IFCHR Character special 
0060000 S_IFBLK Block special 

0100000 S_IFREG Regular 

0030000 S_IFMPC Multiplexed char special 
0070000 S_IFMPB Multiplexed block special 


stat 


Bits Constant Definition 

0004000 S_ISUID Set user ID on execution 

0002000 S_ISGID Set group ID on execution 
0001000 S_ISVTX Save swapped text even after use 
0000400 S_IREAD Read permission, owner 

0000200 S_IWRITE Write permission, owner 

0000100 S_IEXEC Execute/search permission, owner 


The stat function does not work on remote network files. 


If the file is a record file, the st_size field includes carriage-control information. 
Consequently, the st_size value will not correspond to the number of characters 
that can be read from the file. 


Also be aware that for st_size to report a correct value, you need to flush both 
the C RTL and RMS buffers. 


Standard-Compliant stat Structure 
With OpenVMS Version 8.2, the UUSE_STD_STAT feature-test macro and 


standard-compliant stat structure are introduced in support of UNIX 
compatibility. 


With _USE_STD_STAT defined to ENABLE, you get the following behavior: 
e Old struct stat definitions 


Old definitions of struct stat are obsolete. You must recompile your 
applications to access the new features. Existing applications will continue to 
access the old definitions and functions unless they are recompiled to use the 
new features. 


e Function variants 


Calls to stat, fstat, lstat, and ftw accept pointers to structures of the 
new type. Calls to these functions are mapped to the new library entries 
std_stat, std fstat, std _lstat,and std _ftw, respectively. 


e Compatibilities with other feature macros 


_DECC_V4_SOURCE source-code compatibility is not supported. You must 
not enable DECC_V4_SOURCE and _USE_STD_STAT at the same time. 


_VMS_V6_SOURCE binary compatibility is not supported. You must not 
enable _VMS_V6_SOURCE and _USE_STD_STAT at the same time. As a 
result, only UTC (rather than local-time) is supported for the time t fields. 


e Type changes 
The following type changes are in effect: 
— 32-bit gid type gid_t is used. _DECC_SHORT_GID_T is unsupported. 
- _LARGEFILE offsets are used. off_t is forced to 64 bits. 


— Type ino t, representing the file number, is an unsigned int quadword 
(64 bits). Previously, it was an unsigned short. 


— Type dev_t, representing the device id, is an unsigned int quadword 
(64 bits). Previously, it was a 32-bit character pointer. The new type is 
standard because it is arithmetic. 
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— Types blksize t and blkcnt_t are added and defined as unsigned int 
quadwords (64 bits). 


Structure member Changes 
— Two members are added to struct stat: 


blksize t st_blksize; 
blkent_t st_blocks; 


According to the X/Open standard, st_blksize is the filesystem-specific 
preferred I/O blocksize for this file. On OpenVMS systems, st_blksize is 
set to the device buffer size multiplied by the disk cluster size. st_blocks 
is set to the allocated size of the file, in blocks. The blocksize used to 
calculate st_blocks is not necessarily the same as st_blksize and, in 
most cases, will not be the same. 


-— Instruct stat, member st ino is of type ino t. In previous C RTL 
versions, it was of type ino t [3] (array of 3 ino t). Since ino t 
has changed from a word to a quadword, the size of this member has 
increased by one word. The principal significance of this change is that it 
makes st_ino a scalar, which is how most open source applications define 
it. 


-— The new definition of ino t also affects applications that include the 
<dirent.h> header file. In struct dirent, member d_ino changes in the 
same way as the st_ino member of struct stat in <stat.h>. 


— Several macros that are not part of any standard were introduced in 
<stat.h> to facilitate access to the constituent parts of ino_t values: 


S_INO_NUM(ino), S_INO_SEQ(ino), and S_INO_RVN(ino) return the 
FILES-11 file number, sequence number, and relative volume number 
of ino, respectively, as unsigned shorts. 


S_INO_RVN_RVN(ino) returns the byte of the RVN field containing 
the relative volume number; 


S_INO_RVN_NMX(ino) returns the byte of the RVN field containing 
the file number extension. 


Although individual components can be broken out like this, they are 
not part of the X/Open standard and should not be relied on in portable 
applications. 


Semantic changes 


Values of type dev_t are now unique for each device across clusters. An 
algorithm based on device name and allocation class or SCSSYSTEMID 
(for single-pathed devices) calculates the device id value having these 
characteristics, an X/Open standard requirement. Typically, the combination 
of file number and device id uniquely identifies a file in a cluster. 


This change affects stat structure members st_dev and st_rdev. For 
compatibility with previous releases, st_rdev is set to either 0 or st_dev. 


Note (Alpha, 164) 


On OpenVMS Alpha and 164 systems, the stat, fstat, utime, and utimes 
functions have been enhanced to take advantage of the new file-system 
support for POSIX compliant file timestamps. 


Return Values 


stat 


This support is available only on ODS-5 devices on OpenVMS Alpha 
systems beginning with a version of OpenVMS Alpha after Version 7.3. 


Before this change, the stat and fstat functions were setting the values 
of the st_ctime, st_mtime, and st_atime fields based on the following file 
attributes: 


st_ctime - ATR$C_CREDATE (file creation time) 

st_mtime - ATR$C_REVDATE (file revision time) 

st_atime - was always set to st_mtime because no support for file 
access time was available 


Also, for the file-modification time, utime and utimes were modifying 
the ATR$C_REVDATE file attribute, and ignoring the file-access-time 
argument. 


After the change, for a file on an ODS-5 device, the stat and fstat 
functions set the values of the st_ctime, st_mtime, and st atime fields 
based on the following new file attributes: 


st_ctime - ATR$C_ATTDATE (last attribute modification time) 
st_mtime - ATR$C_MODDATE (last data modification time) 
st_atime - ATR$C_ACCDATE (last access time) 


If ATR$C_ACCDATE is zero, as on an ODS-2 device, the stat and fstat 
functions set st_atime to st_mtime. 


For the file-modification time, the utime and utimes functions modify 
both the ATR$C_REVDATE and ATR$C_MODDATE file attributes. For 
the file-access time, these functions modify the ATR$C_ACCDATE file 
attribute. Setting the ATR$C_MODDATE and ATR$C_ACCDATE file 
attributes on an ODS-2 device has no effect. 

For compatibility, the old behavior of stat, fstat, utime, and utimes 
remains the default, regardless of the kind of device. 

The new behavior must be explicitly enabled by defining the DECC$EFS_ 
FILE_TIMESTAMPS logical name to ENABLE before invoking the 
application. Setting this logical does not affect the behavior of stat, 
fstat, utime, and utimes for files on an ODS-2 device. 


Indicates success. 


Indicates an error other than a privilege 
violation; errno is set to indicate the error. 


Indicates a privilege violation. 


REF-599 


statvfs ipna, 164) 


statvfs (Alpha, I64) 


Gets information about a device containing the specified file. 


Format 

#include <statvfs.h> 

int statvfs (const char “restrict path, struct statvfs “restrict buffer); 
Arguments 

path 

Any file on a mounted device. 

buffer 

Pointer to a statvfs structure to hold the returned information. 
Description 


The statvfs function returns descriptive information about the device containing 
the specified file. Read, write, or execute permission of the specified file is not 
required. The returned information is in the format of a statvfs structure, which 
is defined in the <statvfs.h> header file and contains the following members: 


unsigned long f_bsize - Preferred block size. 

unsigned long f frsize - Fundamental block size. 

fsblkcnt_t £ blocks - Total number of blocks in units of f_frsize. 
fsblkcnt_t f_bfree - Total number of free blocks. If £ bfree would assume 
a meaningless value due to the misreporting of free block count by $GETDVI 


for a DFS disk, then f_bfree is set to the maximum block count. 


fsblkcnt_t f_bavail - Number of free blocks available. Set to the unused 
portion of the caller’s disk quota. 


fsfilcnt_t f files - Total number of file serial numbers (for example, 
inodes). 


fsfilcnt_t £ ffree - Total number of free file serial numbers. For OpenVMS 
systems, this value is calculated as freeblocks/clustersize. 


fsfilcnt_t f favail - Number of file serial numbers available to a non- 
privileged process (0 for OpenVMS systems). 


unsigned long f _fsid - File system identifier. This identifier is based on the 
allocation-class device name. This gives a unique value based on device, as 
long as the device is locally mounted. 


unsigned long f_flag - Bit mask representing one or more of the following 
flags: 


ST_RONLY - The volume is read-only. 
ST _NOSUID - The volume has protected subsystems enabled. 
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unsigned long f namemax - Maximum length of a file name. 
char f basetype[64] - Device-type name. 

char f_fstr[64] - Logical volume name. 

char _ reserved[64] - Media type name. 


Upon successful completion, statvfs returns 0 (zero). Otherwise, it returns —1 


and sets errno to indicate the error. 


See also fstatvfs. 


Return Value 


0 
=1 


Sucessful completion. 


Indicates an error. errno is set to one of the 
following: 


EACCHS - Search permission is denied for a 
component of the path prefix. 


EIO - An I/O error occurred while reading 
the device. 


EINTR - A signal was caught during 
execution of the function. 


EOVERFLOW - One of the values to be 
returned cannot be represented correctly in 
the structure pointed to by buffer. 


ENAMETOOLONG - The length of a 
component of the path parameter exceeds 
NAME_MAX, or the length of the path 
parameter exceeds PATH_MAX. 


ENOENT - A component of path does not 
name an existing file, or path is an empty 
string. 


ENOTDIR - A component of the path prefix 
of the path parameter is not a directory. 
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strcasecmp 


Does a case-insensitive comparison of two 7-bit ASCII strings. 


Format 

#include <strings.h> 

int strcasecmp (const char *s1, const char *s2); 
Arguments 

s1 

The first of two strings to compare. 

s2 

The second of two strings to compare. 
Description 


The strcasecmp function is case-insensitive. The returned lexicographic 
difference reflects a conversion to lowercase. 


The strcasecmp function works for 7-bit ASCII compares only. Do not use this 
function for internationalized applications. 


Return Value 


n An integer value greater than, equal to, or less 
than 0 (zero), depending on whether the s/ string 
is greater than, equal to, or less than the s2 
string. 
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strcat 


Concatenates str_2, including the terminating null character, to the end of str_1. 


Format 
#include <string.h> 


char “strcat (char *str_1, const char *str_2); 


Function Variants 
The strcat function has variants named strcat32 and _strcaté4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 

Arguments 
str_1, str_2 
Pointers to null-terminated character strings. 

Description 


See strncat. 


Return Value 


x The address of the first argument, str_1, which 
is assumed to be large enough to hold the 
concatenated result. 


Example 


#include <string.h> 
#include <stdio.h> 


/* This program concatenates two strings using the strcat */ 
/* function, and then manually compares the result of strcat */ 
/* to the expected result. */ 


#define S1LENGTH 10 
#define S2LENGTH 8 


main () 
{ 
static char slbuf[S1LENGTH + S2LENGTH] = "abcmnexyz"; 
static char s2buf[] = " orthis"; 
static char test1[] = "abcmnexyz orthis"; 
int i; 


char *status; 


/* Take static buffer slbuf, concatenate static buffer */ 
/* s2buf to it, and compare the answer in slbuf with the */ 
/* static answer in test1l. * / 


status = strcat(slbuf, s2buf); 
for (1 = 0; 1 <= SILENGTH + S2LENGTH - 2; i++) { 
/* Check for correct returned string. */ 
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if (test1l[i] != slbuf[i]) 
printf ("error in strceat"); 
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strchr 


Format 


Returns the address of the first occurrence of a given character in a null- 
terminated string. 


#include <string.h> 


char *strchr (const char “str, int character); 


Function Variants 


Arguments 


Description 


The strchr function has variants named strchr32 and _strchré4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


str 
A pointer to a null-terminated character string. 


character 
An object of type int. 


This function returns the address of the first occurrence of a given character in a 
null-terminated string. The terminating null character is considered to be part of 
the string. 


Compare with strrchr, which returns the address of the /ast occurrence of a 
given character in a null-terminated string. 


Return Values 


Example 


x The address of the first occurrence of the 
specified character. 

NULL Indicates that the character does not occur in the 
string. 


#include <stdio.h> 
#include <string.h> 


main () 


static char slbuf[] = "abcdefghijkl lkjihgfedcba"; 
int i; 
char *status; 


/* This program checks the strchr function by incrementally */ 
/* going through a string that ascends to the middle and then */ 
/* descends towards the end. */ 
for (i = 0; slbuf[i] != '\0’ && slbuf[i] != ' '; i++) { 
status = strchr(slbuf, slbuf[i]); 
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/* Check for pointer to leftmost character - test 1. 


if (status != &slbuf [i] ) 
printf ("error in strchr") ; 


ef 


strcmp 


strcmp 
Compares two ASCII character strings and returns a negative, 0, or positive 
integer, indicating that the ASCII values of the individual characters in the first 
string are less than, equal to, or greater than the values in the second string. 
Format 
#include <string.h> 
int strcmp (const char “str_7, const char *str_2); 
Arguments 
str_1, str_2 
Pointers to character strings. 
Description 


The strings are compared until a null character is encountered or until the 
strings differ. 


Return Values 


<0 Indicates that str_1 is less than str_2. 
= 0 Indicates that str_1 equals str_2. 
>0 Indicates that str_1 is greater than str_2. 
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strcoll 


Format 


Arguments 


Description 


Compares two strings and returns an integer that indicates if the strings 

differ and how they differ. The function uses the collating information in the 
LC_COLLATE category of the current locale to determine how the comparison is 
performed. 


#include <string.h> 


int strcoll (const char *s7, const char *s2); 


s1, s2 
Pointers to character strings. 


The strcoll function, unlike strcmp, compares two strings in a locale-dependent 
manner. Because no value is reserved for error indication, the application must 
check for one by setting errno to 0 before the function call and testing it after the 
call. 


See also strxfrm. 


Return Values 
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<0 Indicates that s1 is less than s2. 
= 0 Indicates that the strings are equal. 
>0 Indicates that s1 is greater than s2. 


strcpy 


strcpy 
Copies all of source, including the terminating null character, into dest. 


Format 
#include <string.h> 


char *strepy (char *dest, const char *source); 


Function Variants 


The strcpy function has variants named strcpy32 and _strcpy64 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Arguments 


dest 
Pointer to the destination character string. 


source 
Pointer to the source character string. 


Description 


The strcpy function copies source into dest, and stops after copying source’s null 
character. 


The behavior of this function is undefined if the area pointed to by dest overlaps 
the area pointed to by source. 


Return Value 


x The address of dest. 
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strcspn 


Format 


Arguments 


Description 


Returns the length of the prefix of a string that consists entirely of characters not 
in a specified set of characters. 


#include <string.h> 


size_t strespn (const char “str, const char *charset); 


str 
A pointer to a character string. If this character string is a null string, 0 is 
returned. 


charset 
A pointer to a character string containing the set of characters. 


The strcspn function scans the characters in the string, stops when it encounters 
a character found in charset, and returns the length of the string’s initial segment 
formed by characters not found in charset. 


If none of the characters match in the character strings pointed to by str and 
charset, strcspn returns the length of string. 


Return Value 
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x The length of the segment. 


strdup 


strdup 


Duplicates the specified string. 


Format 
#include <string.h> 


char *strdup (const char *s1); 


Function Variants 
The strdup function has variants named strdup32 and _strdupé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 

Argument 
s1 
The string to be duplicated. 

Description 
The strdup function returns a pointer to a string that is an exact duplicate of the 
string pointed to by s1. The malloc function is used to allocate space for the new 
string. The strdup function is provided for compatibility with existing systems. 


Return Values 


x A pointer to the resulting string. 
NULL Indicates an error. 
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strerror 


Format 


Arguments 


Description 


Maps the error number in error_code to a locale-dependent error message string. 


#include <string.h> 
char *strerror (int error_code); (ANSI C) 


char *strerror (int error_code[, int vms_error_code]); (HP C Extension) 


error_code 
An error code. 


vms_error_code 
An OpenVMS error code. 


The strerror function uses the error number in error_code to retrieve the 
appropriate locale-dependent error message. The contents of the error message 
strings are determined by the LC_MESSAGES category of the program’s current 
locale. 


When a program is not compiled with any standards-related feature-test macros 
(see Section 1.5.1), strerror has a second argument (ums_error_code), which is 
used in the following way: 


e If error_code is EVMSERR and there is a second argument, then that second 
argument is used as the vaxcSerrno value. 


e If error_code is EVMSERR and there is no second argument, look at 
vaxcSerrno to get the OpenVMS error condition. 


See the Example section. 


Use of the second argument is not included in the ANSI C definition of strerror 
and is, therefore, not portable. 


Because no return value is reserved to indicate an error, applications should set 
the value of errno to 0, call strerror, and then test the value of errno; a nonzero 
value indicates an error condition. 


Return Value 
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x A pointer to a buffer containing the appropriate 
error message. Do not modify this buffer in 
your programs. Moreover, calls to the strerror 
function may overwrite this buffer with a new 
message. 


Example 


#include 
#include 
#include 
#include 
#include 


main () 


{ 


puts (strerror (EVMSERR) ) ; 

= EVMSERR; 

vaxcSerrno = SS$ LINKEXIT; 

puts (strerror (errno) ) ; 

puts (strerror(EVMSERR, SS$ ABORT)) ; 


errno 


<stdio.h> 
<errno.h> 
<string.h> 
<stdlib.h> 
<ssdef .h> 


exit (1) ; 


} 


Running this example produces the following output: 


nontranslatable vms error code: 


network partner exited 


abort 


strerror 
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strfmon 


strfmon 


Format 


Arguments 


Description 
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Converts a number of monetary values into a string. The conversion is controlled 
by a format string. 


#include <monetary.h> 


ssize_t strfmon (char *s, size_t maxsize, const char *format, ... ); 


s 
A pointer to the resultant string. 


maxsize 
The maximum number of bytes to be stored in the resultant string. 


format 
A pointer to a string that controls the format of the output string. 


The monetary values of type double that are to be formatted for the output 
string. There should be as many values as there are conversion specifications in 
the format string pointed to by format. The function fails if there are insufficient 
values. Excess arguments are ignored. 


The strfmon function creates a string pointed to by s, using the monetary values 
supplied. A maximum of maxsize bytes is copied to s. 


The format string pointed to by format consists of ordinary characters and 
conversion specifications. All ordinary characters are copied unchanged to the 
output string. A conversion specification defines how one of the monetary values 
supplied is formatted in the output string. 


A conversion specification consists of a percent character (%), followed by 
a number of optional characters (see Table REF—5), and concluding with a 
conversion specifier (see Table REF-6). 


If any of the optional characters listed in Table REF—5 is included in a conversion 
specification, they must appear in the order shown. 


strfmon 


Table REF—5 Optional Characters in strfmon Conversion Specifications 


Character 


Meaning 


=character 


field width 


#left_precision 


Use character as the numeric fill character if a left 
precision is specified. The default numeric fill character 
is the space character. The fill character must be 
representable as a single byte in order to work with 
precision and width count. This conversion specifier is 
ignored unless a left precision is specified, and it does not 
affect width filling, which always uses the space character. 


Do not use separator characters to format the number. 
By default, the digits are grouped according to the 
mon_grouping field in the LC_MONETARY category of 
the current locale. 


Add the string specified by the positive_sign or 
negative_sign fields in the current locale. If p_sign_ 
posn or n_sign_posn is set to 0, then parentheses are 
used by default to indicate negative values. Otherwise, 
sign strings are used to indicate the sign of the value. 
You cannot use a + and a ( in the same conversion 
specification. 


Enclose negative values within parentheses. The default 
is taken from the p_sign_posn and n_sign_posn fields in 
the current locale. If p_sign_posn or n_sign_posn is set 

to 0, then parentheses are used by default to indicate 
negative values. Otherwise, sign strings are used to 
indicate the sign of the value. You cannot use a + and ( in 
the same conversion specification. 


Suppress the currency symbol. By default, the currency 
symbol is included. 


Left-justify the value within the field. By default, values 
are right-justified. 


A decimal integer that specifies the minimum field width 
in which to align the result of the conversion. The default 
field width is the smallest field that can contain the result. 


A # followed by a decimal integer specifies the number of 
digits to the left of the radix character. Extra positions 
are filled by the fill character. By default the precision is 
the smallest required for the argument. If grouping is not 
suppressed with the * conversion specifier, and if grouping 
is defined for the current locale, grouping separators are 
inserted before any fill characters are added. Grouping 
separators are not applied to fill characters even if the fill 
character is defined as a digit. 


(continued on next page) 
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Table REF-—5 (Cont.) Optional Characters in strfmon Conversion Specifications 


Character 


Meaning 


.right_precision A period 
number of digits to the right of the radix character. Extra 


positions 


(.) followed by a decimal integer specifies the 


are filled with zeros. The amount is rounded to 


this number of decimal places. If the right precision is 


zero, the 


radix character is not included in the output. By 


default the right precision is defined by the frac_digits or 
int_frac_digits field of the current locale. 


Table REF-6 sitrfmon Conversion Specifiers 


Specifier 


Meaning 


i 


%o 


Use the international currency symbol defined by the 
int_currency_symbol field in the current locale, unless the currency 
symbol has been suppressed. 


Use the local currency symbol defined by the currency_symbol 
field in the current locale, unless the currency symbol has been 


suppressed. 


Output a % character. The conversion specification must be %%; 
none of the optional characters is valid with this specifier. 


Return Values 


Example 
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include 
include 
include 
include 
include 


ain() 


Size t 


<stdlib.h> 
<stdio.h> 
<locale.h> 
<monetary.h> 
<errno.h> 


define MAX BUF SIZE 124 


ret; 


char buffer [MAX BUF SIZE] ; 
double amount = 102593421; 


The number of bytes written to the string pointed 
to by s, not including the null-terminating 
character. 


Indicates an error. The function sets errno to 
one of the following values: 


e EINVAL — A conversion specification is 
syntactically incorrect. 


e E2BIG —- Processing the complete format 
string would produce more than maxsize 
bytes. 


/* Display a monetary amount using the en_US.1S08859-1 */ 
/* locale and a range of different display formats. */ 


strfmon 


if (setlocale(LC_ALL, "en US.IS08859-1") == (char *) NULL) { 
perror("setlocale") ; 
exit (EXIT_FAILURE) ; 


ret = strfmon(buffer, MAX BUF SIZE, "International: %i\n", amount) ; 
printf (buffer) ; 

ret = strfmon(buffer, MAX BUF SIZE, "National: n\n", amount) ; 
printf (buffer) ; 

ret = strfmon(buffer, MAX BUF SIZE, "National: $=*#10n\n", amount) ; 
printf (buffer) ; 

ret = strfmon(buffer, MAX BUF SIZE, "National: $(n\n", -1 * amount); 
printf (buffer) ; 

ret = strfmon(buffer, MAX BUF SIZE, "National: *!n\n", amount) ; 
printf (buffer) ; 


} 


Running the example program produces the following result: 


International: USD 102,593,421.00 


National: $102,593,421.00 
National: $**102,593,421.00 
National: ($102,593,421.00) 
National: 102593421.00 


REF-617 


strftime 


strftime 


Format 


Uses date and time information stored in a tm structure to create an output 
string. The format of the output string is controlled by a format string. 


#include <time.h> 


size_t strftime (char *s, size_t maxsize, const char “format, const struct tm *timeptn); 


Function Variants 


Arguments 


Description 
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Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the strftime function 
that is equivalent to the behavior before OpenVMS Version 7.0. 


s 
A pointer to the resultant string. 


maxsize 
The maximum number of bytes to be stored in the resultant string, including the 
null terminator. 


format 
A pointer to a string that controls the format of the output string. 


timeptr 
A pointer to the local time (tm) structure. The tm structure is defined in the 
<time.h> header file. 


The strftime function uses data in the structure pointed to by timeptr to create 
the string pointed to by s. A maximum of maxsize bytes is copied to s. 


The format string consists of zero or more conversion specifications and ordinary 
characters. All ordinary characters (including the terminating null character) are 
copied unchanged into the output string. A conversion specification defines how 
data in the tm structure is formatted in the output string. 


A conversion specification consists of a percent (%) character followed by 

one or more optional characters (see Table REF-—7), and concluding with a 
conversion specifier (see Table REF-—8). If any of the optional characters listed in 
Table REF-—7 are specified, they must appear in the order shown in the table. 


The strftime function behaves as if it called tzset. 


strftime 


Table REF—7 Optional Elements of strftime Conversion Specifications 


Element Meaning 

- Optional with the field width to specify that the field is left-justified 
and padded with spaces. This cannot be used with the 0 element. 

0 Optional with the field width to specify that the field is right- 
justified and padded with zeros. This cannot be used with the — 
element. 

field width A decimal integer that specifies the maximum field width 

.-precision A decimal integer that specifies the precision of data in a field. 


For the d, H, I, j, m, M, o, S, U, w, W, y, and Y conversion 
specifiers, the precision specifier is the minimum number of digits 
to appear in the field. If the conversion specification has fewer 
digits than that specified by the precision, leading zeros are added. 
For the a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and 

% conversion specifiers, the precision specifier is the maximum 
number of characters to appear in the field. If the conversion 
specification has more characters than that specified by the 
precision, characters are truncated on the right. 

The default precision for the d, H, I, m, M, 0, S, U, w, W, y and Y 
conversion specifiers is 2; the default precision for the j conversion 
specifier is 3. 


Note that the list of conversion specifications in Table REF-—7 are extensions to 
the XPG4 specification. 


Table REF-8 lists the conversion specifiers. The strftime function uses fields 

in the LC_TIME category of the program’s current locale to provide a value. For 
example, if $B is specified, the function accesses the mon field in LC_TIME to find 
the full month name for the month specified in the tm structure. The result of 
using invalid conversion specifiers is undefined. 


Table REF-8 strftime Conversion Specifiers 


Specifier 


Replaced by 


Qawneo7 fw 


Ec 


The locale’s abbreviated weekday name 

The locale’s full weekday name 

The locale’s abbreviated month name 

The locale’s full month name 

The locale’s appropriate date and time representation 


The century number (the year divided by 100 and truncated to 
an integer) as a decimal number (00 — 99) 


The day of the month as a decimal number (01 — 31) 
Same as %m/%d/%y 


The day of the month as a decimal number (1 — 31) in a 2-digit 
field with the leading space character fill 


The locale’s alternative date and time representation 


(continued on next page) 
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Table REF-8 (Cont.) sitrftime Conversion Specifiers 


Specifier Replaced by 

EC The name of the base year (period) in the locale’s alternative 
representation 

EX The locale’s alternative date representation 

EX The locale’s alternative time representation 

Ey The offset from the base year (%EC) in the locale’s alternative 
representation 

EY The locale’s full alternative year representation 

h Same as %b 

H The hour (24-hour clock) as a decimal number (00 — 23) 

I The hour (12-hour clock) as a decimal number (01 — 12) 

5 The day of the year as a decimal number (001 — 366) 

m The month as a decimal number (01 — 12) 

M The minute as a decimal number (00 — 59) 

n The new-line character 

Od The day of the month using the locale’s alternative numeric 
symbols 

Oe The date of the month using the locale’s alternative numeric 
symbols 

OH The hour (24-hour clock) using the locale’s alternative numeric 
symbols 

OI The hour (12-hour clock) using the locale’s alternative numeric 
symbols 

Om The month using the locale’s alternative numeric symbols 

OM The minutes using the locale’s alternative numeric symbols 

os The seconds using the locale’s alternative numeric symbols 

Ou The weekday as a number in the locale’s alternative 
representation (Monday=1) 

OU The week number of the year (Sunday as the first day of the 
week) using the locale’s alternative numeric symbols 

OV The week number of the year (Monday as the first day of 
the week) as a decimal number (01 — 53) using the locale’s 
alternative numeric symbols. If the week containing January 1 
has four or more days in the new year, it is considered as week 
1. Otherwise, it is considered as week 53 of the previous year, 
and the next week is week 1. 

Ow The weekday as a number (Sunday=0) using the locale’s 
alternative numeric symbols 

OW The week number of the year (Monday as the first day of the 
week) using the locale’s alternative numeric symbols 

Oy The year without the century using the locale’s alternative 


numeric symbols 


(continued on next page) 
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Table REF-8 (Cont.) sirftime Conversion Specifiers 


Specifier 


Replaced by 


p 


GQebHttaen ws 


oe 


The locale’s equivalent of the AM/PM designations associated 
with a 12-hour clock 


The time in AM/PM notation 

The time in 24-hour notation (%H: %M) 

The second as a decimal number (00 — 61) 

The tab character 

The time (%H:%M:%S) 

The weekday as a decimal number between 1 and 7 (Monday=1) 


The week number of the year (the first Sunday as the first day 
of week 1) as a decimal number (00 — 53) 


The week number of the year (Monday as the first day of the 
week) as a decimal number (00 — 53). If the week containing 
January 1 has four or more days in the new year, it is 
considered as week 1. Otherwise, it is considered as week 
53 of the previous year, and the next week is week 1. 


The weekday as a decimal number (0 [Sunday] — 6) 


The week number of the year (the first Monday as the first day 
of week 1) as a decimal number (00 — 53) 


The locale’s appropriate date representation 
The locale’s appropriate time representation 
The year without century as a decimal number (00 — 99) 
The year with century as a decimal number 


Time-zone name or abbreviation. If time-zone information is not 
available, no character is output. 


Literal % character. 


#include 
#include 
#include 
#include 
#include 


The number of characters placed into the array 
pointed to by s, not including the terminating 
null character. 


Indicates an error occurred. The contents of the 
array are indeterminate. 


<stdlib.h> 
<stdio.h> 
<time.h> 
<locale.h> 
<errno.h> 


#define NUM OF DATES 7 
#define BUF SIZE 256 


/* This program formats a number of different dates, once */ 
/* using the C locale and then using the fr_FR.1S08859-1 */ 
/* locale. Date and time formatting is done using strftime(). */ 
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strftime 


REF-622 


main () 


{ 


int count, 
ab 
char buffer [BUF SIZE] ; 
struct tm *tm ptr; 
time_t time list [NUM_OF DATES] = 
{500, 68200000, 694223999, 694224000, 
704900000, 705000000, 705900000}; 


/* Display dates using the C locale */ 
printf ("\nUsing the C locale:\n\n"); 


setlocale(LC_ALL, "C"); 


for (i = 0; i < NUM_OF DATES; i++) { 
/* Convert to a tm structure */ 
tm_ptr = localtime(&time_list[i]); 


/* Format the date and time */ 
count = strftime(buffer, BUF SIZE, 
"Date: SA %d %B %YsnTime: 6T%n%n", tm_ptr); 


if (count == 0) { 
perror("strftime") ; 
exit (EXIT_FAILURE) ; 


/* Print the result */ 
printf (buffer) ; 


/* Display dates using the fr_FR.I 
printf ("\nUsing the fr_FR.1S08859- 


setlocale(LC_ ALL, "fr FR.1S08859-1 


for (i = 0; i < NUM_OF DATES; i++ 
/* Convert to a tm structure * 
tm_ptr = localtime(&time list 


/* Format the date and time */ 
count = strftime(buffer, BUF_S 
"Date: SA $d %B %Y%nTin 
if (count == 0) { 
perror ("strftime") ; 
exit (EXIT_FAILURE) ; 


/* Print the result */ 
printf (buffer) ; 


} 


S08859-1 locale */ 
1 locale:\n\n") ; 


we 
{ 

/ 

a) 


IZE, 
e: sTsnsn", tm_ptr); 


Running the example program produces the following result: 


Using the C locale: 


Date: 
Time: 
Date: 
Time: 
Date: 
Time: 
Date: 
Time: 
Date: 
Time: 


Thursday 01 January 1970 
00:08:20 

Tuesday 29 February 1972 
08:26:40 

Tuesday 31 December 1991 
23:59:59 

Wednesday 01 January 1992 
00:00:00 

Sunday 03 May 1992 
13:33:20 


the fr FR.1S08859-1 locale: 


: jeudi 
: 00:08 
: mardi 
: 08:26 


: mardi 
2 23259! 


: lundi 
¢ Ds 20s 


00 


00 


01 


220 


29 


740 


31 
59 


: mercredi 
: 00:00: 


00 


: dimanche 


: 13:33:20 


04 
00 


: vendredi 
: 03:20: 


00 


: Monday 04 May 1992 
fT 20% 


: Friday 15 May 1992 
: 03:20: 


janvier 1970 


février 1972 


décembre 1991 


01 janvier 1992 


03 mai 1992 


mai 1992 


15 mai 1992 


strftime 
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strlen 
Returns the length of a string of ASCII characters. The returned length does not 
include the terminating null character (\ 0). 
Format 
#include <string.h> 
size_t strlen (const char “str; 
Argument 


str 
A pointer to the character string. 


Return Value 


x The length of the string. 


REF-624 


strncasecmp 


strncasecmp 


Format 


Arguments 


Description 


Does a case-insensitive comparison between two 7-bit ASCII strings. 


#include <strings.h> 


int strncasecmp (const char *s?, const char “s2, size_t n); 


s1 
The first of two strings to compare. 


$2 
The second of two strings to compare. 


n 
The maximum number of bytes in a string to compare. 


The strncasecmp function is case-insensitive. The returned lexicographic 
difference reflects a conversion to lowercase. The strncasecmp function is 
similar to the strcasecmp function, but also compares size. If the size specified 
by n is read before a NULL, the comparison stops. 


The strcasecmp function works for 7-bit ASCII compares only. Do not use this 
function for internationalized applications. 


Return Value 


n An integer value greater than, equal to, or less 
than 0 (zero), depending on whether s/ is greater 
than, equal to, or less than s2. 
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strncat 


Format 


Appends not more than maxchar characters from str_2 to the end of str_1. 


#include <string.h> 


char *strncat (char *str_1, const char “str_2, size_t maxchan; 


Function Variants 


Arguments 


Description 


The strncat function has variants named strncat32 and _strncaté64 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


str_1, str_2 
Pointers to null-terminated character strings. 


maxchar 

The number of characters to concatenate from str_2, unless strncat first 
encounters a null terminator in str_2. If maxchar is 0, no characters are copied 
from str_2. 


A null character is always appended to the result of the strncat function. If 
strncat reaches the specified maximum, it sets the next byte in str_1 to the null 
character. 


Return Value 
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x The address of the first argument, str_1, which 
is assumed to be large enough to hold the 
concatenated result. 


strncmp 


strncmp 


Format 


Arguments 


Description 


Compares not more than maxchar characters of two ASCII character strings and 
returns a negative, 0, or positive integer, indicating that the ASCII values of the 
individual characters in the first string are less than, equal to, or greater than 
the values in the second string. 


#include <string.h> 


int strncmp (const char *str_1, const char *str_2, size_t maxchar); 


str_1, str_2 
Pointers to character strings. 


maxchar 

The maximum number of characters (beginning with the first) to search in both 
str_1 and str_2. If maxchar is 0, no comparison is performed and 0 is returned 
(the strings are considered equal). 


The strncmp function compares no more than maxchar characters from the string 
pointed to by str_1 to the string pointed to by str_2. The strings are compared 
until a null character is encountered, the strings differ, or maxchar is reached. 
Characters that follow a difference or a null character are not compared. 


Return Values 


Examples 


<0 Indicates that str_1 is less than str_2. 
= 0 Indicates that str_1 equals str_2. 
>0 Indicates that str_1 is greater than str_2. 


#include <string.h> 
#include <stdio.h> 


main () 
printf( "%d\n", strncemp("abcde", "abc", 3)); 


When linked and executed, this example returns 0, because the first 3 
characters of the 2 strings are equal: 


$ run tmp 
0 
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#include <string.h> 
#include <stdio.h> 


main () 


printf( "%d\n", strnemp("abcde", "abc", 4)); 


When linked and executed, this example returns a value greater than 0 
because the first 4 characters of the 2 strings are not equal (The "d" in the 
first string is not equal to the null character in the second): 


$ run tmp 
100 


strncpy 


strncpy 


Format 


Copies not more than maxchar characters from source into dest. 


#include <string.h> 


char “strncpy (char “dest, const char *source, size_t maxchar); 


Function Variants 


Arguments 


Description 


The strncpy function has variants named strncpy32 and _strncpyé64 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


dest 
Pointer to the destination character string. 


source 
Pointer to the source character string. 


maxchar 
The maximum number of characters to copy from source to dest up to but not 
including the null terminator of source. 


The strncpy function copies no more than maxchar characters from source to 
dest, up to but not including the null terminator of source. If source contains less 
than maxchar characters, dest is padded with null characters. If source contains 
greater than or equal to maxchar characters, as many characters as possible are 
copied to dest. Be aware that the dest argument might not be terminated by a 
null character after a call to strncpy. 


Return Value 


x The address of dest. 
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strnien 

Returns the number of bytes in a string. 
Format 

#include <string.h> 

size_t strnlen (const char *s, size_t n); 
Arguments 

s 

Pointer to the string. 

n 

The maximum number of characters to examine. 
Description 


The strnlen function returns the number of bytes in the string pointed to by 

s. The string length value does not include the terminating null character. The 
strnien function counts bytes until the first null byte or until n bytes have been 
examined. 


Return Value 


n The length of the string. 
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strpbrk 


Format 


Searches a string for the occurrence of one of a specified set of characters. 


#include <string.h> 


char “strpbrk (const char “str, const char *charset); 


Function Variants 


Arguments 


Description 


The strpbrk function has variants named strpbrk32 and _strpbrké64 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


str 
A pointer to a character string. If this character string is a null string, 0 is 
returned. 


charset 
A pointer to a character string containing the set of characters for which the 
function will search. 


The strpbrk function scans the characters in the string, stops when it encounters 
a character found in charset, and returns the address of the first character in the 
string that appears in the character set. 


Return Values 


x The address of the first character in the string 
that is in the set. 
NULL Indicates that no character is in the set. 
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strptime 


Format 


Converts a character string into date and time values that are stored in a tm 
structure. Conversion is controlled by a format string. 


#include <time.h> 


char *strptime (const char *buf, const char *format, struct tm *timeptr); 


Function Variants 


Arguments 


Description 
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The strptime function has variants named strptime32 and _strptimeé4 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


buf 
A pointer to the character string to convert. 


format 
A pointer to the string that defines how the input string is converted. 


timeptr 
A pointer to the local time structure. The tm structure is defined in the <time.h> 
header file. 


The strptime function converts the string pointed to by buf into values that are 
stored in the structure pointed to by timeptr. The string pointed to by format 
defines how the conversion is performed. 


The strptime function modifies only those fields in the tm structure that have 
corresponding conversion specifications in the format. In particular, strptime 
never sets the tm_isdst member of the tm structure. 


The format string consists of zero or more directives. A directive is composed of 
one of the following: 


e One or more white-space characters (as defined by the isspace function). 
This directive causes the function to read input up to the first character that 
is not a white-space character. 


e Any character other than the percent character (%) or a white-space 
character. This directive causes the function to read the next character. 
The character read must be the same as the character that comprises the 
directive. If the character is different, the function fails. 


e Acconversion specification. A conversion specification defines how characters 
in the input string are interpreted as values that are then stored in the 
tm structure. A conversion specification consists of a percent (%) character 
followed by a conversion specifier. Table REF—9 lists the valid conversion 
specifications. 


strptime 


The strptime function uses fields in the LC_TIME category of the program’s 
current locale to provide a value. 


Note 


To be compliant with X/Open CAE Specification System Interfaces and 
Headers Issue 5 (commonly known as XPG5), the strptime function 
processes the "%y" directive differently than in previous versions of the 
HP C RTL. 


With Version 6.4 and higher of the C compiler, for a two-digit year within 
the century if no century is specified, "%y" directive values range from: 


e 69 to 99 refer to years in the twentieth century (1969 to 1999 
inclusive) 


e 00 to 68 refer to years in the twenty-first century (2000 to 2068 
inclusive) 


In previous (XPG4-compliant) versions of the HP C RTL, strptime 
interpreted a two-digit year with no century specified as a year within the 
twentieth century. 


The XPG5-compliant strptime is now the default version in the HP C 
RTL. 


To obtain the old, XPG4-compliant strptime function behavior, specify 
one of the following: 


¢ Define the DECC$XPG4_STRPTIME logical name as follows: 
$ DEFINE DECCSXPG4 STRPTIME ENABLE 
or: 
e Call the XPG4 strptime directly as the function decc$strptime xpg4. 


To return to using the XPG5 strptime version, DEASSIGN the 
DECC$XPG4_STRPTIME logical name: 


$ DEASSIGN DECCSXPG4_STRPTIME 


Table REF-9 strptime Conversion Specifications 


Specification Replaced by 


sa The weekday name. This is either the abbreviated or the full 
name. 

SA Same as %a. 

$b The month name. This is either the abbreviated or the full name. 

$B Same as %b. 

SC The date and time using the locale’s date format. 

SEC The locale’s alternative date and time representation. 


(continued on next page) 
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Table REF-9 (Cont.) strptime Conversion Specifications 


Specification Replaced by 


SC The century number (the year divided by 100 and truncated to 
an integer) as a decimal number (00 — 99). Leading zeros are 
permitted. 

SEC The name of the base year (period) in the locale’s alternative 
representation. 

$d The day of the month as a decimal number (01 — 31). Leading 
zeros are permitted. 

%0d The day of the month using the locale’s alternative numeric 
symbols. 

$D Same as %m/%d/%y. 

Se Same as %d. 

%0e The date of the month using the locale’s alternative numeric 
symbols. 

sh Same as %b. 

SH The hour (24-hour clock) as a decimal number (00 — 23). Leading 
zeros are permitted. 

%OH The hour (24-hour clock) using the locale’s alternative numeric 
symbols. 

SI The hour (12-hour clock) as a decimal number (01 — 12). Leading 
zeros are permitted. 

S01 The hour (12-hour clock) using the locale’s alternative numeric 
symbols. 

aa The day of the year as a decimal number (001 — 366). 

Sm The month as a decimal number (01 — 12). Leading zeros are 
permitted. 

Om The month using the locale’s alternative numeric symbols. 

SM The minute as a decimal number (00 — 59). Leading zeros are 
permitted. 

30M The minutes using the locale’s alternative numeric symbols. 

en Any white-space character. 

Sp The locale’s equivalent of the AM/PM designations associated with 
a 12-hour clock. 

Sr The time in AM/PM notation (%1:%M:%S %p). 

SR The time in 24-hour notation (%H: %M). 

%S The second as a decimal number (00 — 61). Leading zeros are 


permitted. 


(2) 
ip) 


The seconds using the locale’s alternative numeric symbols. 
Any white-space character. 
The time (%H: 3M: %S). 


HP AP ol 
ct 


| 
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Table REF-9 (Cont.) strptime Conversion Specifications 


Specification 


Replaced by 


Fe x 
x OM 


K 


JP AP AP 'P— D's CO 
P< 


\ 
fe 
K 


oe 


The week number of the year (the first Sunday as the first day 
of week 1) as a decimal number (00 — 53). Leading zeros are 
permitted. 


The week number of the year (Sunday as the first day of the week) 
using the locale’s alternative numeric symbols. 


The weekday as a decimal number (0 [Sunday] — 6). Leading zeros 
are permitted. 


The weekday as a number (Sunday=0) using the locale’s alternative 
numeric symbols. 


The week number of the year (the first Monday as the first day 
of week 1) as a decimal number (00 — 53). Leading zeros are 
permitted. 


The week number of the year (Monday as the first day of the week) 
using the locale’s alternative numeric symbols. 


The locale’s appropriate date representation. 
The locale’s alternative date representation. 
The locale’s alternative time representation. 
The locale’s appropriate time representation. 
The year without century as a decimal number (00 — 99). 


The offset from the base year (%EC) in the locale’s alternative 
representation. 


The year without the century using the locale’s alternative numeric 
symbols. 


The year with century as a decimal number. 
The locale’s full alternative year representation. 
Literal % character. 


Return Values 


Example 


NULL 


#incl 
incl 
incl 
incl 
incl 
#incl 


defi 


ude 
ude 
ude 
ude 
ude 
ude 


A pointer to the character following the last 
character parsed. 


Indicates that an error occurred. The contents of 
the tm structure are undefined. 


<string.h> 
<stdlib.h> 
<stdio.h> 
<time.h> 
<locale.h> 
<errno.h> 


#define NUM_OF DATES 7 
ne BUF SIZE 256 
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/* This program takes a number of date and time strings and */ 
/* converts them into tm structs using strptime(). These tm */ 
/* structs are then passed to strftime() which will reverse the */ 
/* process. The resulting strings are then compared with the */ 


/* originals and if a difference is found then an error is */ 
/* displayed. */ 
main () 

{ 

int count, 


Lj 
char buffer [BUF SIZE] ; 
char *ret_val; 
struct tm time_struct; 
char dates [NUM_OF DATES] [BUF SIZE] = 


"Thursday 01 January 1970 00:08:20", 
"Tuesday 29 February 1972 08:26:40", 
"Tuesday 31 December 1991 23:59:59", 
"Wednesday 01 January 1992 00:00:00", 
"Sunday 03 May 1992 13:33:20", 
"Monday 04 May 1992 17:20:00", 
"Friday 15 May 1992 03:20:00"}; 


for (i = 0; i < NUM_OF DATES; i++) { 
/* Convert to a tm structure */ 
ret_val = strptime(dates[i], "SA sd %B %Y ®T", &time_struct) ; 


/* Check the return value */ 

if (ret_val == (char *) NULL) { 
perror ("strptime") ; 
exit (EXIT_FAILURE) ; 


/* Convert the time structure back to a formatted string */ 
count = strftime(buffer, BUF SIZE, "SA sd SB SY ST", &time_struct) ; 


/* Check the return value */ 
if (count == 0) 

perror ("strftime") ; 

exit (EXIT_FAILURE) ; 


/* Check the result */ 
if (strcemp(buffer, dates[i]) != 0) { 
printf("Error: Converted string differs from the original\n") ; 


else { 
printf ("Successfully converted <%s>\n", dates[i]); 


} 
} 


Running the example program produces the following result: 


Successfully converted <Thursday 01 January 1970 00:08:20> 
Successfully converted <Tuesday 29 February 1972 08:26:40> 
Successfully converted <Tuesday 31 December 1991 23:59:59> 
Successfully converted <Wednesday 01 January 1992 00:00:00> 
Successfully converted <Sunday 03 May 1992 13:33:20> 
Successfully converted <Monday 04 May 1992 17:20:00> 
Successfully converted <Friday 15 May 1992 03:20:00> 
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Format 


Returns the address of the last occurrence of a given character in a null- 
terminated string. 


#include <string.h> 


char *strrchr (const char “str, int character); 


Function Variants 


Arguments 


Description 


The strrchr function has variants named _strrchr32 and _strrchré4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


str 
A pointer to a null-terminated character string. 


character 
An object of type int. 


This function returns the address of the /ast occurrence of a given character in a 
null-terminated string. The terminating null character is considered to be part of 
the string. 


Compare with strchr, which returns the address of the first occurrence of a given 
character in a null-terminated string. 


Return Values 


x The address of the last occurrence of the specified 
character. 

NULL Indicates that the character does not occur in the 
string. 
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Format 


Separates strings. 


#include <string.h> 


char *strsep (char **stringp, char *delim); 


Function Variants 


Arguments 


Description 


The strsep function has variants named _strsep32 and _strsep64 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


stringp 
A pointer to a pointer to a character string. 


delim 
A pointer to a string containing characters to be used as delimiters. 


The strsep function locates in stringp, the first occurrence of any character in 
delim (or the terminating ’\ 0’ character) and replaces it with a’\0’. The location 
of the next character after the delimiter character (or NULL, if the end of the 
string is reached) is stored in the stringp argument. The original value of the 
stringp argument is returned. 


You can detect an "empty" field; one caused by two adjacent delimiter characters, 
by comparing the location referenced by the pointer returned in the stringp 
argument to ’\0’. 


The stringp argument is initially NULL, strsep returns NULL. 


Return Values 


Example 
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x The address of the string pointed to by stringp. 
NULL Indicates that stringp is NULL. 


The following example uses strsep to parse a string, containing token delimited 
by white space, into an argument vector: 


char **ap, **argv[10], *inputstring; 


for (ap = argv; (*ap = strsep(&inputstring, " \t")) != NULL;) 
if (**ap != '\0") 
++ap; 


strspn 


strspn 


Format 


Arguments 


Description 


Returns the length of the prefix of a string that consists entirely of characters 
from a set of characters. 


#include <string.h> 


size_t strspn (const char “str, const char *charseb); 


str 
A pointer to a character string. If this string is a null string, 0 is returned. 


charset 
A pointer to a character string containing the characters for which the function 
will search. 


The strspn function scans the characters in the string, stops when it encounters 
a character not found in charset, and returns the length of the string’s initial 
segment formed by characters found in charset. 


Return Value 


x The length of the segment. 
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strstr 


Locates the first occurrence in the string pointed to by si of the sequence of 
characters in the string pointed to by s2. 


Format 
#include <string.h> 


char *strstr (const char *s7, const char *s2); 


Function Variants 


The strstr function has variants named _strstr32 and _strstré4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Arguments 


s1, s2 
Pointers to character strings. 


Return Values 


Pointer A pointer to the located string. 
NULL Indicates that the string was not found. 


Example 


#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 


main () 


static char lookin[]="that this is a test was at the end"; 


putchar(‘\n’); 

printf ("String: %s\n", &lookin[0] ); 

putchar(‘\n’); 

printf ("Addr: %s\n", &lookin[0] ); 

printf ("this: %s\n", strstr( &lookin[0] ,"this") ); 

printf ("that: %s\n", strstr( &lookin[0] , "that" ) ); 
OT Ne dee 


printf ("NULL: s\n", strstr( &lookin 


printf ("was: %s\n", strstr( &lookin[0], "was" ) ); 

printf ("at: %s\n", strstr( &lookin[0], "at" ) ); 

printf ("the end: %s\n", strstr( &lookin[0], "the end") ); 
putchar(‘\n’); 

exit (0); 


} 


This example produces the following results: 
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S$ RUN STRSTR EXAMPLE 

String: that this is a test was at the end 
Addr: that this is a test was at the end 
this: this is a test was at the end 

that: that this is a test was at the end 
NULL: that this is a test was at the end 
was: was at the end 

at: at this is a test was at the end 

the end: the end 

$ 
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strtod 


Format 


Converts a given string to a double-precision number. 


#include <stdlib.h> 


double strtod (const char *nptr, char **endptr); 


Function Variants 


Arguments 


Description 
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The strtod function has variants named _strtod32 and _strtodé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


nptr 
A pointer to the character string to be converted to a double-precision number. 


endptr 

The address of an object where the function can store the address of the first 
unrecognized character that terminates the scan. If endptr is a NULL pointer, 
the address of the first unrecognized character is not retained. 


The strtod function recognizes an optional sequence of white-space characters 
(as defined by isspace), then an optional plus or minus sign, then a sequence 
of digits optionally containing a radix character, then an optional letter (e or E) 
followed by an optionally signed integer. The first unrecognized character ends 
the conversion. 


The string is interpreted by the same rules used to interpret floating constants. 


The radix character is defined the program’s current locale (category 
LC_NUMERIC). 


This function returns the converted value. For strtod, overflows are accounted 
for in the following manner: 


e Ifthe correct value causes an overflow, HUGE_VAL (with a plus or minus sign 
according to the sign of the value) is returned and errno is set to ERANGE. 


e If the correct value causes an underflow, 0 is returned and errno is set to 


ERANGE. 


If the string starts with an unrecognized character, then the conversion is not 
performed, *endptr is set to nptr, a 0 value is returned, and errno is set to 
EINVAL.) 


Return Values 


+HUGE_VAL 


strtod 


The converted string. 


Indicates the conversion could not be performed. 
errno is set to one of the following: 


e EINVAL - No conversion could be performed. 


e ERANGE - The value would cause an 
underflow. 


e ENOMEM - Not enough memory available 
for internal conversion buffer. 


Overflow occurred; errno is set to ERANGE. 
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strtok, strtok_r 


Format 


Split strings into tokens. 


#include <string.h> 
char *strtok (char *s1, const char *s2); 


char *strtok_r (char *s, const char *sep, char **/asts); 


Function Variants 


Arguments 


Description 
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The strtok function has variants named strtok32 and _strtok64 for use with 
32-bit and 64-bit pointer sizes, respectively. Likewise, the strtok_r function 
has variants named strtok_r32 and _strtok_ré64. See Section 1.10 for more 
information on using pointer-size-specific functions. 


s1 
On the first call, a pointer to a string containing zero or more text tokens. On all 
subsequent calls for that string, a NULL pointer. 


s2 
A pointer to a separator string consisting of one or more characters. The 
separator string may differ from call to call. 


s 
A null-terminated string that is a sequence of zero or more text tokens separated 
by spans of one or more characters from the separator string sep. 


sep 
A null-terminated string of separator characters. This separator string can be 
different from call to call. 


lasts 
A pointer that points to a user-provided pointer to stored information needed for 
strtok_r to continue scanning the same string. 


The strtok function locates text tokens in a given string. The text tokens are 
delimited by one or more characters from a separator string that you specify. The 
function keeps track of its position in the string between calls and, as successive 
calls are made, the function works through the string, identifying the text token 
following the one identified by the previous call. 


A token in s/ starts at the first character that is not a character in the separator 
string s2 and ends either at the end of the string or at (but not including) a 
separator character. 


The first call to the strtok function returns a pointer to the first character in the 
first token and writes a null character into s1 immediately following the returned 
token. Each subsequent call (with the value of the first argument remaining 
NULL) returns a pointer to a subsequent token in the string originally pointed 
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to by s1. When no tokens remain in the string, the strtok function returns a 
NULL pointer. (This can occur on the first call to strtok if the string is empty or 
contains only separator characters.) 


Since strtok inserts null characters into s1 to delimit tokens, s1 cannot be a 
const object. 


The strtok_r function is the reentrant version of strtok. The function strtok_r 
considers the null-terminated string s as a sequence of zero or more text tokens 
separated by spans of one or more characters from the separator string sep. The 
lasts argument points to a user-provided pointer to stored information needed for 
strtok_r to continue scanning the same string. 


In the first call to strtok_r, s points to a null-terminated string, sep points to a 
null-terminated string of separator characters, and the value pointed to by lasts 
is ignored. The strtok_r function returns a pointer to the first character of the 
first token, writes a null character into s immediately following the returned 
token, and updates the pointer to which lasts points. 


In subsequent calls, s is a NULL pointer and Jasts is unchanged from the previous 
call so that subsequent calls move through the string s, returning successive 
tokens until no tokens remain. The separator string sep can be different from call 
to call. When no token remains in s, a NULL pointer is returned. 


Return Values 


Examples 


x A pointer to the first character of the parsed 
token in the string. 


NULL Indicates that there are no tokens remaining in 
the string. 
A, : F 
#include <stdio.h> 
#include <string.h> 
main () 
{ 
static char str[] = "...ab..cd,,ef.hi"; 
printf("|%s|\n", strtok(str, ".")); 
printf("|%s|\n", strtok(NULL, ",")); 
print£("|/%s}\n", strtok(NULL, ",.")); 
printf("|%s}\n", strtok(NULL, ",.")); 


} 


Running this example program produces the following results: 


S$ RUN STRTOK EXAMPLE1 
ab | 

cd | 

ef 

hi 
$ 
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#include <stdio.h> 
#include <string.h> 


main () 


} 


char *ptr 


! 


string[30]; 


/* The first character not in the string "-" is "A". The 
/* token ends at "C. 


strcpy(s 


tring, "ABC"); 


ptr = strtok(string, "-"); 


printf (" 


$s|\n", ptr); 


/* Returns NULL because no characters not in separator 


/* string "-" were found (i.e. 


/* were 


strcpy(s 


found) 


tring, "-"); 


ptr = strtok (string, mom). 
if (ptr == NULL) 


prin 


tf("ptr is NULL\n"); 


only separator characters 


Running this example program produces the following results: 


S$ RUN STRTOK EXAMPLE2 
| abc | 
ptr is NULL 


$ 
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strtol 


Format 


Converts strings of ASCII characters to the appropriate numeric values. 


#include <stdlib.h> 


long int strtol (const char *nptr, char **endptr, int base); 


Function Variants 


Arguments 


Description 


The strtol function has variants named _strtol32 and _strtolé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


npir 
A pointer to the character string to be converted to a long. 


endptr 

The address of an object where the function can store a pointer to the first 
unrecognized character encountered in the conversion process (that is, the 
character that follows the last character in the string being converted). If endptr 
is a NULL pointer, the address of the first unrecognized character is not retained. 


base 
The value, 2 through 36, to use as the base for the conversion. 


The strtol function recognizes strings in various formats, depending on the value 
of the base. This function ignores any leading white-space characters (as defined 
by isspace in <ctype.h>) in the given string. It recognizes an optional plus or 
minus sign, then a sequence of digits or letters that may represent an integer 
constant according to the value of the base. The first unrecognized character ends 
the conversion. 


Leading zeros after the optional sign are ignored, and Ox or OX is ignored if the 
base is 16. 


If base is 0, the sequence of characters is interpreted by the same rules used to 
interpret an integer constant: after the optional sign, a leading 0 indicates octal 
conversion, a leading Ox or 0X indicates hexadecimal conversion, and any other 
combination of leading characters indicates decimal conversion. 


Truncation from long to int can take place after assignment or by an explicit 
cast (arithmetic exceptions not withstanding). The function call atol (str) is 
equivalent to strtol (str, (char**)NULL, 10). 
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x 


LONG_MAX or LONG_MIN 


The converted value. 


Indicates that the converted value would cause 
an overflow. 


Indicates that the string starts with an 
unrecognized character or that the value for 
base is invalid. If the string starts with an 
unrecognized character, *endptr is set to nptr. 
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strtoq, strtoll (iia 164 


Format 


Convert strings of ASCII characters to the appropriate numeric values. strtoll 
is a synonym for strtogq. 


#include <stdlib.h> 
_int64 strtoq (const char *nptr, char **endptr, int base); 


__int64 strtoll (const char *nptr, char **endptr, int base); 


Function Variants 


Arguments 


Description 


These functions have variants named _strtoq32, strtoll32 and 
_strtog64, strtoll64 for use with 32-bit and 64-bit pointer sizes, respectively. 
See Section 1.10 for more information on using pointer-size-specific functions. 


nptr 
A pointer to the character string to be converted toan _inté4. 


endpir 

The address of an object where the function can store a pointer to the first 
unrecognized character encountered in the conversion process (that is, the 
character that follows the last character in the string being converted). If endptr 
is a NULL pointer, the address of the first unrecognized character is not retained. 


base 
The value, 2 through 36, to use as the base for the conversion. 


The strtog and strtoll functions recognize strings in various formats, 
depending on the value of the base. Any leading white-space characters (as 
defined by isspace in <ctype.h>) in the given string are ignored. The functions 
recognize an optional plus or minus sign, then a sequence of digits or letters that 
may represent an integer constant according to the value of the base. The first 
unrecognized character ends the conversion. 


Leading zeros after the optional sign are ignored, and Ox or OX is ignored if the 
base is 16. 


If base is 0, the sequence of characters is interpreted by the same rules used to 
interpret an integer constant: after the optional sign, a leading 0 indicates octal 
conversion, a leading Ox or 0X indicates hexadecimal conversion, and any other 
combination of leading characters indicates decimal conversion. 


The function call atog (str) is equivalent to strtog (str, (char**)NULL, 10). 
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Return Values 


x 


__INT64_MAX or 
__INT64_MIN 


0 
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The converted value. 


Indicates that the converted value would cause 
an overflow. 


Indicates that the string starts with an 
unrecognized character or that the value for 
base is invalid. If the string starts with an 
unrecognized character, *endpir is set to nptr. 


strtoul 


strtoul 


Format 


Converts the initial portion of the string pointed to by nptr to an unsigned long 
integer. 


#include <stdlib.h> 


unsigned long int strtoul (const char *nptr, char **endptr, int base); 


Function Variants 


Arguments 


The strtoul function has variants named strtoul32 and _strtoulé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


nptr 
A pointer to the character string to be converted to an unsigned long. 


endpir 

The address of an object where the function can store a pointer to a pointer to the 
first unrecognized character encountered in the conversion process (that is, the 
character that follows the last character in the string being converted). If endptr 
is a NULL pointer, the address of the first unrecognized character is not retained. 


base 
The value, 2 through 36, to use as the base for the conversion. Leading zeros 
after the optional sign are ignored, and Ox or OX is ignored if the base is 16. 


If the base is 0, the sequence of characters is interpreted by the same rules used 
to interpret an integer constant: after the optional sign, a leading 0 indicates 
octal conversion, a leading Ox or OX indicates hexadecimal conversion, and any 
other combination of leading characters indicates decimal conversion. 


Return Values 


The converted value. 


0 Indicates that the string starts with an 
unrecognized character or that the value for 
base is invalid. If the string starts with an 
unrecognized character, *endptr is set to nptr. 


ULONG MAX Indicates that the converted value would cause 
an overflow. 
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strtouq, strtoull (aipic, 164 


strtougq, strtoull ipic, 164 


Format 


Convert the initial portion of the string pointed to by nptr to an unsigned 
__inté4 integer. strtoull is a synonym for strtoug. 


#include <stdlib.h> 
unsigned __int64 strtouq (const char “nptr, char **endpitr, int base); 


unsigned __int64 strtoull (const char *nptr, char **endptr, int base); 


Function Variants 


Arguments 


These functions have variants named strtouq32, strtoull32 and 
_strtoug64, strtoullé4 for use with 32-bit and 64-bit pointer sizes, respectively. 
See Section 1.10 for more information on using pointer-size-specific functions. 


nptr 
A pointer to the character string to be converted to an unsigned __inté4. 


endptr 

The address of an object where the function can store a pointer to a pointer to the 
first unrecognized character encountered in the conversion process (that is, the 
character that follows the last character in the string being converted). If endptr 
is a NULL pointer, the address of the first unrecognized character is not retained. 


base 
The value, 2 through 36, to use as the base for the conversion. Leading zeros 
after the optional sign are ignored, and Ox or OX is ignored if the base is 16. 


If the base is 0, the sequence of characters is interpreted by the same rules used 
to interpret an integer constant: after the optional sign, a leading 0 indicates 
octal conversion, a leading Ox or OX indicates hexadecimal conversion, and any 
other combination of leading characters indicates decimal conversion. 


Return Values 
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x The converted value. 


0 Indicates that the string starts with an 
unrecognized character or that the value for 
base is invalid. If the string starts with an 
unrecognized character, *endptr is set to nptr. 


__UINT64_MAX Indicates that the converted value would cause 
an overflow. 


strxfrm 


strxfrm 


Format 


Arguments 


Description 


Changes a string such that the changed string can be passed to the strcmp 
function, and produce the same result as passing the unchanged string to the 
strcoll function. 


#include <string.h> 


size_t strxfrm (char *s7, const char *s2, size_t maxchar); 


s1, s2 
Pointers to character strings. 


maxchar 
The maximum number of bytes (including the null terminator) to be stored in s/. 


The strxfrm function transforms the string pointed to by s2, and stores the 
resulting string in the array pointed to by s1. No more than maxchar bytes, 
including the null terminator, are placed into the array pointed to by sJ. 


If the value of maxchar is less than the required size to store the transformed 
string (including the terminating null), the contents of the array pointed to by s1 
is indeterminate. In such a case, the function returns the size of the transformed 
string. 


If maxchar is 0, then s1 is allowed to be a NULL pointer, and the function returns 
the required size of the s1 array before making the transformation. 


The string comparison functions, strcoll and strcmp, can produce different 
results given the same two strings to compare. The reason for this is that strcmp 
does a straightforward comparison of the code point values of the characters in 
the strings, whereas strcoll uses the locale information to do the comparison. 
Depending on the locale, the strcoll comparison can be a multipass operation, 
which is slower than strcmp. 


The purpose of the strxfrm function is to transform strings in such a way that if 
you pass two transformed strings to the strcmp function, the result is the same 
as passing the two original strings to the strcoll function. The strxfrm function 
is useful in applications that need to do a large number of comparisons on the 
same strings using strcoll. In this case, it might be more efficient (depending on 
the locale) to transform the strings once using strxfrm, and then do comparisons 
using strcmp. 
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strxfrm 


Return Value 


Example 
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Length of the resulting string pointed to by s/, 
not including the terminating null character. 

No return value is reserved for error indication. 
However, the function can set errno to EINVAL 
— The string pointed to by s2 contains characters 
outside the domain of the collating sequence. 


This program verifies that two transformed strings when */ 
passed through strxfrm and then compared, provide the same */ 
result as if passed through strcoll without any */ 
transformation. 


include <string.h> 
include <stdio.h> 
include <stdlib.h> 
include <locale.h> 


define BUFF SIZE 256 


main () 


char stringl [BUFF SIZE] ; 
char string2 [BUFF SIZE] ; 
int errno; 

int coll result; 
int strcmp result; 
size t strxfrm_resultl; 
size t strxfrm_result2; 


/* setlocale to French locale */ 


if (setlocale(LC_ ALL, "fr FR.1S08859-1") == NULL) { 
perror("setlocale") ; 
exit (EXIT_FAILURE) ; 


/* collate string 1 and string 2 and store the result */ 


errno = 0; 
coll result = strcoll("<a‘>bcd", "abcz") ; 
if (errno) 

perror("strcoll") ; 

exit (EXIT_FAILURE) ; 


else { 
/* Transform the strings (using strxfrm) into stringl */ 
/* and string2 */ 


strxfrm_resultl = strxfrm(stringl, "<a‘>bcd", BUFF SIZE) ; 


if (strxfrm_result1 == ((size t) - 1)) { 
perror ("strxfrm") ; 
exit (EXIT_FAILURE) ; 


else if (strxfrm_resultl > BUFF SIZE) { 
perror("\n** String is too long **\n"); 
exit (EXIT_FAILURE) ; 


strxfrm 


else { 
strxfrm_result2 = strxfrm(string2, "abcz", BUFF SIZE) ; 
if (strxfrm_result2 == ((size t) - 1)) { 


perror ("strxfrm") ; 
exit (EXIT_FAILURE) ; 


else if (strxfrm_result2 > BUFF SIZE) { 
perror("\n** String is too long **\n"); 
exit (EXIT_FAILURE) ; 


/* Compare the two transformed strings and verify */ 
/* that the result is the same as the result from +*/ 


/* strcoll on the original strings */ 
else { 

strcmp result = strcemp(stringl, string2) ; 

if (strcmp result == 0 && (coll_result == 0)) { 


printf ("\nReturn value from strcoll() and " 
"return value from strcmp() are both zero."); 
printf ("\nThe program was successful\n\n") ; 


else if ((strcmp result < 0) && (coll_result < 0)) { 
printf ("\nReturn value from strcoll() and " 
"return value from strcemp() are less than zero."); 
printf("\nThe program successful\n\n") ; 


} 


else if ((strcmp result > 0) && (coll_result > 0)) { 
printf ("\nReturn value from strcoll() and " 
"return value from strcmp() are greater than zero."); 
printf("\nThe program was successful\n\n") ; 


printf ("** Error **\n"); 
printf ("\nReturn values are not of the same type"); 


} 
} 


Running the example program produces the following result: 


Return value from strcoll() and return value 
from stremp() are less than zero. 
The program was successful 
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subwin 


subwin 


Format 


Arguments 


Description 


Creates a new subwindow with numlines lines and numcols columns starting at 
the coordinates (begin_y,begin_x) on the terminal screen. 


#include <curses.h> 


WINDOW “subwin (WINDOW *win, int numlines, int numcols, int begin_y, int begin_x); 


win 
A pointer to the parent window. 


numlines 

The number of lines in the subwindow. If numlines is 0, then the function sets 
that dimension to LINES — begin_y. To get a subwindow of dimensions LINES 
by COLS, use the following format: 


subwin (win, 0, 0, 0, 0) 


numcols 

The number of columns in the subwindow. If numcols is 0, then the function sets 
that dimension to COLS — begin_x. To get a subwindow of dimensions LINES by 
COLS, use the following format: 


subwin (win, 0, 0, 0, 0) 


begin_y 
A window coordinate at which the subwindow is to be created. 


begin_x 
A window coordinate at which the subwindow is to be created. 


When creating the subwindow, begin_y and begin_x are relative to the entire 
terminal screen. If either numlines or numcols is 0, then the subwin function sets 
that dimension to (LINES — begin_y) or (COLS — begin_x), respectively. 


The window pointed to by win must be large enough to contain the entire area of 
the subwindow. Any changes made to either window within the coordinates of the 
subwindow appear on both windows. 


Return Values 
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window pointer A pointer to an instance of the structure window 
corresponding to the newly created subwindow. 


ERR Indicates an error. 


swab 


swab 


Format 


Arguments 


Description 


Swaps bytes. 


#include <unistd.h> 


void swab (const void “src, void *dest, ssize_t nbytes); 


src 
A pointer to the location of the string to copy. 


dest 
A pointer to where you want the results copied. 


nbytes 
The number of bytes to copy. Make this argument an even value. When it is an 
odd value, the swab function uses nbytes —1 instead. 


The swab function copies the number of bytes specified by nbytes from the location 
pointed to by src to the array pointed to by dest. The function then exchanges 
adjacent bytes. If a copy takes place between objects that overlap, the result is 
undefined. 
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swprintf 


swprintf 


Format 


Arguments 


Description 


Writes output to an array of wide characters under control of the wide-character 
format string. 


#include <wchar.h> 


int swprintf (wchar_t *s, size_t n, const wchar_t “format, ... ); 


s 
A pointer to the resulting wide-character sequence. 


n 
The maximum number of wide characters that can be written to an array pointed 
to by s, including a terminating null wide character. 


format 

A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, the output sources can be omitted. 
Otherwise, the function calls must have exactly as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Excess output pointers, if any, are ignored. 


The swprintf function is equivalent to the fwprintf function, except that the 
first argument specifies an array of wide characters instead of a stream. 


No more than n wide characters are written, including a terminating null wide 
character, which is always added (unless n is 0). 


See also fwprintf. 


Return Values 
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x The number of wide characters written, not 
counting the terminating null wide character. 


Negative value Indicates an error. Either n or more wide 
characters were requested to be written, or a 
conversion error occurred, in which case errno is 
set to EILSEQ. 


swscanf 


swscanf 


Format 


Arguments 


Description 


Reads input from a wide-character string under control of the wide-character 
format string. 


#include <wchar.h> 


int swscanf (const wchar_t “s, const wchar_t “format, ... ); 


s 
A pointer to a wide-character string from which the input is to be obtained. 


format 

A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


Optional expressions whose results correspond to conversion specifications given 
in the format specification. 


If no conversion specifications are given, you can omit the input pointers. 
Otherwise, the function calls must have exactly as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


The swscanf function is equivalent to the fwscanf function, except that the first 
argument specifies a wide-character string rather than a stream. Reaching the 
end of the wide-character string is the same as encountering EOF for the fwscanf 
function. 


See also fwscanf. 


Return Values 


x The number of input items assigned, sometimes 
fewer than provided for, or even 0 in the event of 
an early matching failure. 

EOF Indicates an error. An input failure occurred 
before any conversion. 
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symlink (pra, 164 


symlink (Alpha, 164) 


Format 


Arguments 


Description 


Creates a symbolic link containing the specified contents. 


#include <unistd.h> 


int symlink (const char *link_contents, const char *link_name); 


link_contents 
Contents of the symbolic link file, specified as a text string representing the 
pathname to which the symbolic link will point. 


link_name 
The text string representing the name of the symbolic link file. 


A symbolic link is a special kind of file that points to another file. It is a directory 
entry that associates a filename with a text string that is interpreted as a POSIX 
pathname when accessed by certain services. A symbolic link is implemented 

on OpenVMS systems as a file of organization SPECIAL and type SYMBOLIC_ 
LINK. 


The symlink function creates a symbolic link (Jink_name) containing the specified 
contents (link_contents). No attempt is made at link creation time to interpret 
the symbolic link contents. 


See also readlink, unlink, realpath, lchown, and lstat. 


Return Values 
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0 Successful completion 


symlink (ipa, 164) 


Indicates an error. errno is set to indicate the 
error: 


EACCES — Write permission is denied in the 
directory where the symbolic link is being 
created, or search permission is denied for a 
component of the path prefix of link_name. 


EEXIST — The link_name argument names 
an existing file or symbolic link. 


ENAMETOOLONG -— The length of the link_ 
name argument exceeds PATH_MAX, or a 
pathname component is longer than NAME_ 
MAX, or the length of the link_contents 
argument is longer than SYMLINK_MAX. 


ENOSPC — The directory in which the entry 
for the new symbolic link is being placed 
cannot be extended because no space is left 
on the file system containing the directory, 
or the new symbolic link cannot be created 
because no space is left on the file system 
that would contain the link, or the file system 
is out of file-allocation resources. 


Any errno value from creat, fsync, lstat, or 
write. 
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sysconf 


sysconf 


Format 


Argument 


Description 


Table REF-10 


Gets configurable system variables. 


#include <unistd.h> 


long int sysconf (int name); 


name 
Specifies the system variable to be queried. 


The sysconf function provides a method for determining the current value of a 
configurable system limit or whether optional features are supported. 


You supply a symbolic constant in the name argument, and sysconf returns a 
value for the corresponding system variable: 


e The symbolic constants defined in the <unistd.h> header file. 


e The system variables are defined in the <limits.h> and <unistd.h> header 
files. 


Table REF—10 lists the system variables returned by the sysconf function, and 
the symbolic constants that you can supply as the name value. 


sysconf Argument and Return Values 


Symbolic Consiant for 


System Variable Returned name Meaning 
ISO POSIX-1 
ARG_MAX _SC_ARG_MAX The maximum length, in bytes, of the 


CHILD_MAX 


CLK_TCK 


arguments for one of the exec functions, 
including environment data. 

_SC_CHILD MAX The maximum number of simultaneous 
processes for each real user ID. 

_SC_CLK_TCK The number of clock ticks per second. 
The value of CLK_TCK can be variable. 
Do not assume that CLK_TCK is a 
compile-time constant. 


NGROUPS_MAX _SC_NGROUPS_MAX The maximum number of simultaneous 


OPEN_MAX 
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supplementary group IDs for each 
process. 


_SC_OPEN_MAX The maximum number of files that one 
process can have open at one time. 


(continued on next page) 


sysconf 


Table REF-10 (Cont.) sysconf Argument and Return Values 


Symbolic Constant for 
System Variable Returned name 


Meaning 


ISO POSIX-1 


STREAM_MAX _SC_STREAM_MAX 


TZNAME_MAX _SC_TZNAME_MAX 


_POSIX_JOB_CONTROL _SC_JOB_CONTROL 


POSIX_SAVED_IDS _SC_SAVED_IDS 


_POSIX_VERSION _SC_VERSION 


The number of streams that one process 
can have open at one time. 


The maximum number of bytes 
supported for the name of a time zone 
(not the length of the TZ environmental 
variable). 


This variable has a value of 1 if the 
system supports job control; otherwise, 
—1 is returned. 


This variable has a value of 1 if each 
process has a saved set user ID and a 
saved set group ID; otherwise, —1 is 
returned. 


The date of approval of the most current 
version of the POSIX-1 standard that the 
system supports. The date is a 6-digit 
number, with the first 4 digits signifying 
the year and the last 2 digits the month. 
If POSIX_VERSION is not defined, —1 is 
returned. 

Different versions of the POSIX-1 
standard are periodically approved by 
the IEEE Standards Board, and the 
date of approval is used to distinguish 
between different versions. 


ISO POSIX-2 


BC_BASE_MAX SC_BC_BASE_MAX 


BC_DIM_MAX _SC_BC_DIM_MAXx 


BC_SCALE_MAX SC_BC_SCALE 
MAX 

BC_STRING_MAX _SC_BC_STRING_ 
MAX 

COLL_WEIGHTS_MAX _SC_COLL_ 
WEIGHTS_MAX 


The maximum value allowed for the 
obase variable with the bc command. 
The maximum number of elements 
permitted in an array by the bc 
command. 

The maximum value allowed for the 
scale variable with the bc command. 
The maximum length of string constants 
accepted by the bc command. 

The maximum number of weights 
that can be assigned to an entry in 
the LC_COLLATE locale-dependent 
information in a locale definition file. 


(continued on next page) 
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sysconf 


Table REF-10 (Cont.) sysconf Argument and Return Values 


Symbolic Constant for 
System Variable Returned name 


Meaning 


ISO POSIX-2 


EXPR_NEST_MAX SC_EXPR_NEST 
MAX 


LINE_MAX _SC_LINE_MAX 


RE_DUP_MAX _SC_RE_DUP_MAX 


_POSIX2_CHAR_TERM _SC_2_CHAR_TERM 


_POSIX2_C_BIND _SC_2_C_BIND 


_POSIX2_C_DEV _SC_2_C_DEV 


_POSIX2_C_VERSION _SC_2_C_VERSION 


_POSIX2_VERSION _SC_2_VERSION 


_POSIX2_FORT_DEV _SC_2_FORT_DEV 


_POSIX2_FORT_RUN _SC_2_FORT_RUN 
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The maximum number of expressions 
that you can nest within parentheses by 
the expr command. 


The maximum length, in bytes, of a 
command input line (either standard 
input or another file) when the utility is 
described as processing text files. The 
length includes room for the trailing 
new-line character. 


The maximum number of repeated 
occurrences of a regular expression 
permitted when using the interval 
notation arguments, such as the m 
and n arguments with the ed command. 


This variable has a value of 1 if the 
system supports at least one terminal 
type; otherwise, —1 is returned. 


This variable has a value of 1 if the 
system supports the C language binding 
option; otherwise, —1 is returned. 


This variable has a value of 1 if the 
system supports the optional C Language 
Development Utilities from the ISO 
POSIX-2 standard; otherwise, —1 is 
returned. 


Integer value indicating the version of 
the ISO POSIX-2 standard (C language 
binding). It changes with each new 
version of the ISO POSIX-2 standard. 


Integer value indicating the version of 
the ISO POSIX-2 standard (Commands). 
It changes with each new version of the 
ISO POSIX-2 standard. 

The variable has a value of 1 if 

the system supports the Fortran 
Development Utilities Option from the 
ISO POSIX-2 standard; otherwise, —1 is 
returned. 

The variable has a value of 1 if the 
system supports the Fortran Runtime 
Utilities Option from the ISO POSIX-2 
standard; otherwise, —1 is returned. 
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Table REF-10 (Cont.) sysconf Argument and Return Values 


System Variable Returned 


Symbolic Constant for 
name 


Meaning 


ISO POSIX-2 


_POSIX2_LOCALEDEF 


_POSIX2_SW_DEV 


_POSIX2_UPE 


_SC_2_LOCALEDEF 


_SC_2_SW_DEV 


_SC_2_UPE 


The variable has a value of 1 if the 
system supports the creation of new 
locales with the localedef command; 
otherwise, —1 is returned. 


The variable has a value of 1 if 

the system supports the Software 
Development Utilities Option from the 
ISO POSIX-2 standard; otherwise, —1 is 
returned. 

The variable has a value of 1 if the 
system supports the User Portability 
Utilities Option; otherwise, —1 is 
returned. 


POSIX 1003.1c-1995 


_POSIX_THREADS 


_POSIX_THREAD_ATTR 


_SC_THREADS 


SC_THREAD_ 


STACKSIZE 


_POSIX_THREAD_ 
PRIORITY_SCHEDULING 


POSIX_THREAD_SAFE 


ATTR_STACKSIZE 


_SC_THREAD_ 
PRIORITY_ 
SCHEDULING 


SC_THREAD_ 


FUNCTIONS 


PTHREAD_ 
DESTRUCTOR_ 
ITERATIONS 


SAFE_FUNCTIONS 


_SC_THREAD_ 
DESTRUCTOR_ 
ITERATIONS 


This variable has a value of 1 if the 
system supports POSIX threads; 
otherwise, —1 is returned. 


This variable has a value of 1 if the 
system supports the POSIX threads 
stack size attribute; otherwise, —1 is 
returned. 


The 1003.1c implementation supports 
the realtime scheduling functions. 


TRUE if the implementation supports 
the thread-safe ANSI C functions in 
POSIX 1003.1c. 


When a thread terminates, DECthreads 
iterates through all non-NULL thread- 
specific data values in the thread, and 
calls a registered destructor routine 

(if any) for each. It is possible for a 
destructor routine to create new values 
for one or more thread-specific data keys. 
In that case, DECthreads goes through 
the entire process again. 
_SC_THREAD_DESTRUCTOR_ 
ITERATIONS is the maximum number 
of times the implementation loops before 
it terminates the thread even if there are 
still non-NULL values. 


(continued on next page) 
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Table REF-10 (Cont.) sysconf Argument and Return Values 


System Variable Returned 


Symbolic Constant for 
name 


Meaning 


POSIX 1003.1c-1995 


PTHREAD_KEYS_MAX _SC_THREAD_ The maximum number of thread-specific 
KEYS_MAX data keys that an application can create. 
PTHREAD_STACK_MIN _SC_THREAD_ The minimum allowed size of a stack for 
STACK_MIN a new thread. Any lower value specified 
for the "stacksize" thread attribute is 
rounded up. 
UINT_MAX _SC_THREAD_ The maximum number of threads an 
THREADS_MAX application is allowed to create. Since 
DECthreads does not enforce any fixed 
limit, this value is —1. 
X/Open 


_XOPEN_VERSION 


PASS_MAX 


XOPEN_CRYPT 


XOPEN_ENH_I18N 


XOPEN_SHM 


_SC_XOPEN_ 
VERSION 
_SC_PASS_MAX 


_SC_XOPEN_CRYPT 


_SC_XOPEN_ENH_ 
118N 


_SC_XOPEN_SHM 


An integer indicating the most current 
version of the X/Open standard that the 
system supports. 


Maximum number of significant bytes in 
a password (not including terminating 
null). 


This variable has a value of 1 if the 
system supports the X/Open Encryption 
Feature Group; otherwise, —1 is 
returned. 


This variable has a value of 1 if the 
system supports the X/Open enhanced 
Internationalization Feature Group; 
otherwise, —1 is returned. 

This variable has a value of 1 if the 
system supports the X/Open Shared 
Memory Feature Group; otherwise, —1 is 
returned. 


X/Open Extended 


ATEXIT_MAX 


PAGESIZE 
PAGE_SIZE 
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_SC_ATEXIT_MAX 


_SC_PAGESIZE 
_SC_PAGE_SIZE 


The maximum number of functions that 
you can register with atexit per process. 
Size, in bytes, of a page. 

Same as PAGESIZE. If either PAGESIZE 


or PAGE_SIZE is defined, the other is 
defined with the same value. 
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Table REF-10 (Cont.) sysconf Argument and Return Values 


Symbolic Constant for 


System Variable Returned name Meaning 


X/Open Extended 


IOV_MAX 


XOPEN_UNIX 


_SC_IOV_MAX Maximum number of iovec structures 
that one process has available for use 
with readv or writev. 


_SC_XOPEN_UNIX This variable has a value of 1 if the 
system supports the X/Open CAE 
Specification, August 1994, System 
Interfaces and Headers, Issue 4, 
Version 2, (ISBN: 1-85912-037-7, C435); 
otherwise, —1 is returned. 


Other 


N/A 


SC_CPU_CHIP Returns information for the processor 
TYPE type. See the description after this table. 


For the SC_CPU_CHIP_TYPE symbolic constant: 


On Alpha servers, sysconf returns the architecture type (2), as given by the 
$GETSYI system service. 


Integrity processor information is stored in CPUID register 3. This register 
contains a 64-bit integer divided into 1-byte fields indicating version 
information related to the processor implementation. The sysconf function 
returns the low-order longword with the following information: 


31 24 23 16 15 8 7 0 


These fields are described in the following table: 


Field Bits Description 


number 7:0 Index of the largest implemented CPUID register (one less 


rev 


than the number of implemented CPUID registers). This 
value will be at least 4. 

15:8 Processor revision number. An 8-bit value that represents 
the revision or stepping of this processor implementation 
within the processor model. 


model 23:16 Processor model number. A unique 8-bit value 


representing the processor model within the processor 
family. 


family 31:24 Processor family number. A unique 8-bit value 


representing the processor family. 
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The current variable value on the system. The 
value does not change during the lifetime of the 
calling process. 

Indicates an error. 

If the value of the name argument is invalid, 
errno is set to indicate the error. 

If the value of the name argument is undefined, 
errno is unchanged. 


system 


system 


Format 


Argument 


Description 


Passes a given string to the host environment to be executed by a command 
processor. This function is nonreentrant. 


#include <stdlib.h> 


int system (const char *string); 


string 

A pointer to the string to be executed. If string is NULL, a nonzero value is 
returned. The string is a DCL command, not the name of an image. To execute 
an image, use one of the exec routines. 


The system function spawns a subprocess and executes the command specified 
by string in that subprocess. The system function waits for the subprocess 

to complete before returning the subprocess status as the return value of the 
function. 


The subprocess is spawned within the system call by a call to vfork. Because 
of this, a call to system should not be made after a call to vfork and before the 
corresponding call to an exec function. 


For OpenVMS Version 7.0 and higher systems, if you include <stdlib.h> and 
compile with the _POSIX_EXIT feature-test macro set, then the system function 
returns the status as if it called waitpid to wait for the child. Therefore, use the 
WIFEXITED and WEXITSTATUS macros to retrieve the exit status in the range 
of 0 to 255. 


You set the _POSIX_EXIT feature-test macro by using /DEFINE=_POSIX_EXIT 
or #define _POSIX_EXIT at the top of your file, before any file inclusions. 


Return Value 


Example 


nonzero value If string is NULL, a value of 1 is returned, 
indicating that the system function is supported. 
If string is not NULL, the value is the subprocess 
OpenVMS return status. 


#include <stdlib.h> 
#include <stdio.h> 
#include <unistd.h> /* write, close */ 
#include <fcntl.h> /* Creat */ 
main () 

int status, 

fd; 
/* Creat a file we are sure is there */ 
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system 


} 


fd = creat ("system.test", 0); 
write(fd, "this is an example of using system", 34); 
close (fd) ; 


if (system(NULL)) { 
status = system ("DIR/NOHEAD/NOTRAIL/SIZE SYSTEM. TEST") ; 
printf ("system status = %d\n", status); 


else 
printf ("system() not supported.\n") ; 


Running this example program produces the following result: 


DISK3$: [JONES .CRTL.2059.SRC] SYSTEM. TEST; 1 


L 


system status = 1 
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tan 


tan 


Returns a double value that is the tangent of its radian argument. 


Format 
#include <math.h> 
double tan (double x); 
float tanf (float x); (Alpha, 164) 
long double tan! (long double x); (Alpha, 164) 
double tand (double x); (Alpha, 164) 
float tandf (float x); (Alpha, 164) 


long double tand! (long double x); (Alpha, 164) 


Argument 


x 
A radian expressed as a real number. 


Description 
The tan functions compute the tangent of x, measured in radians. 


The tand functions compute the tangent of x, measured in degrees. 


Return Values 


x The tangent of the argument. 

HUGE_VAL x is a singular point (... —3a/2, —1/2, 1/2... ). 
NaN x is NaN; errno is set to EDOM. 

0 x is Infinity; errno is set to EDOM. 
tHUGE_VAL Overflow occurred; errno is set to ERANGE. 

0 Underflow occurred; errno is set to ERANGE. 
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tanh 


Returns the hyperbolic tangent of its argument. 


float tanhf (float x); (Apna, 164) 


long double tanhl (long double x); (Alpha, 164) 


tanh 
Format 
#include <math.h> 
double tanh (double x); 
Argument 
x 
A real number. 
Description 


The tanh functions return the hyperbolic tangent their argument, calculated as 
(e**x — e**(—x)/(e**x + e**(—x)). 


Return Values 


n 


HUGE_VAL 


NaN 
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The hyperbolic tangent of the argument. 


The argument is too large; errno is set to 
ERANGE. 


x is NaN; errno is set to EDOM. 
Underflow occurred; errno is set to ERANGE. 


telldir 


telldir 
Returns the current location associated with a specified directory stream. 
Performs operations on directories. 
Format 
#include <dirent.h> 
long int telldir (DIR *dir_pointer); 
Argument 


dir_pointer 
A pointer to the DIR structure of an open directory. 


Description 


The telldir function returns the current location associated with the specified 
directory stream. 


Return Values 


x The current location. 


—1 Indicates an error and is further specified in the 
global errno. 
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tempnam 


tempnam 


Format 


Arguments 


Description 
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Constructs the name for a temporary file. 


#include <stdio.h> 


char *tempnam (const char “directory, const char “prefix, . . . ;) 


directory 
A pointer to the pathname of the directory where you want to create a file. 


prefix 

A pointer to an initial character sequence of the file name. The prefix argument 
can be null, or it can point to a string of up to five characters used as the first 
characters of the temporary file name. 


An optional argument that can be either 1 or 0. If you specify 1, tempnam returns 
the file specification in OpenVMS format. If you specify 0, tempnam returns the 
file specification in UNIX style format. For more information about UNIX style 
directory specifications, see Section 1.4.3. 


The tempnam function generates file names for temporary files. It allows you to 
control the choice of a directory. 


If the directory argument is null or points to a string that is not a pathname for 
an appropriate directory, the pathname defined as P_tmpdir in the <stdio.h> 
header file is used. 


You can bypass the selection of a pathname by providing the TMPDIR environment 
variable in the user environment. The value of the TMPDIR variable is a pathname 
for the desired temporary file directory. 


Use the prefix argument to specify a prefix of up to five characters for the 
temporary file name. 


The tempnam function returns a pointer to the generated pathname, suitable for 
use in a subsequent call to the free function. 


See also free. 


Note 


In contrast to tmpnam, tempnam does not have to generate a different file 
name on each call. tempnam generates a new file name only if the file with 
the specified name exists. If you need a unique file name on each call, use 
tmpnam instead of tempnam. 


Return Values 


NULL 


tempnam 


A pointer to the generated pathname, suitable 
for use in a subsequent call to the free function. 


An error occurred; errno is set to indicate the 
error. 
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tgamma dipia, 164) 


tgammMa Apia, 164 


Format 


Argument 


Description 


Returns the gamma function of its argument. 


#include <math.h> 
double tgamma (double x); 
float tgammaf (float x); 


long double tgammal (long double x); 


x 
A real value. 


The tgamma functions compute the gamma function of x. 


Return Values 


REF-676 


Upon success, the gamma function of x. 
If x is negative. errno is set to EDOM. 
Overflow occurred or x is +0. errno is set to 


If x is NaN or —Inf. errno is set to EDOM. 


n 
—1 
+tHUGE_VAL 
ERANGE. 
NaN 
x If x is +Inf. 


time 


time 


Returns the time (expressed as Universal Coordinated Time) elapsed since 
00:00:00, January 1, 1970, in seconds. 

Format 
#include <time.h> 


time_t time (time_t *time_location); 


Function Variants 


Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the time function that is 
equivalent to the behavior before OpenVMS Version 7.0. 


Argument 


time_location 
Either NULL or a pointer to the place where the returned time is also stored. 
The time_t type is defined in the <time.h> header file as follows: 


typedef unsigned long int time _t; 
Return Values 


x The time elapsed past the Epoch. 


(time_t)(—1) Indicates an error. If the value of 
SYS$TIMEZONE_DIFFERENTIAL logical is 
wrong, the function will fail with errno set to 
EINVAL. 
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times 


times 


Format 


Argument 


Description 


Passes back the accumulated times of the current process and its terminated 
child processes. 


#include <times.h> 
clock_t times (struct tms “buffer); (OpenVMS V7.0 and higher) 


void times (tbuffer_t *buffer); (pre OpenVMS V7.0) 


buffer 
A pointer to the terminal buffer. 


For both process and children times, the structure breaks down the time by user 
and system time. Since the OpenVMS system does not differentiate between 
system and user time, all system times are returned as 0. Accumulated CPU 
times are returned in 10-millisecond units. 


Only the accumulated times for child processes running a C main program or a 
program that calls VAXC$CRTL_INIT or DECC$CRTL_INIT are included. 


On OpenVMS Version 7.0 and higher systems, the times function returns the 
elapsed real time in clock ticks since an arbitrary reference time in the past (for 
example, system startup time). This reference time does not change from one 
times function call to another. The return value can overflow the possible range 
of type clock t values. When times fails, it returns a value of —1. The HP C 
RTL uses system-boot time as its reference time. 


Return Values 
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x The elapsed real time in clock ticks since system- 
boot time. 
(clock _t)(—1) Indicates an error. 


tmpfile 


tmpfile 

Creates a temporary file that is opened for update. 
Format 

#include <stdio.h> 

FILE *tmpfile (void); 
Description 


The file exists only for the duration of the process, or until the file is closed and is 
preserved across calls to vfork. 


Return Values 


x The address of a file pointer (defined in the 
<stdio.h> header file). 
NULL Indicates an error. 


REF-679 


tmpnam 


impnam 


Generates file names that can be safely used for a temporary file. 


Format 
#include <stdio.h> 


char *tmpnam (char *name); 


Function Variants 


The tmpnam function has variants named tmpnam32 and _tmpnamé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Argument 


name 

A character string containing a name to use in place of filename arguments in 
functions or macros. Successive calls to tmpnam with a null argument cause the 
function to overwrite the current name. 


Return Value 


x If the name argument is the NULL pointer 
value NULL, tmpnam returns the address of an 
internal storage area. If name is not NULL, then 
it is considered the address of an area of length 
L_tmpnam (defined in the <stdio.h> header file). 
In this case, tmpnam returns the name argument 
as the result. 
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toascii 


Converts its argument, an 8-bit ASCII character, to a 7-bit ASCII character. 


toascii 
Format 

#include <ctype.h> 

int toascii (char character); 
Argument 


character 


An object of type char. 


Return Value 


A 7-bit ASCII character. 
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tolower 


tolower 

Converts a character to lowercase. 
Format 

#include <ctype.h> 

int tolower (int character); 
Argument 


character 
An object of type int representable as an unsigned char or the value of EOF. For 
any other value, the behavior is undefined. 

Description 


If the argument represents an uppercase letter, and there is a corresponding 
lowercase letter, as defined by character type information in the program locale 
category LC_CTYPE, the corresponding lowercase letter is returned. 


If the argument is not an uppercase character, it is returned unchanged. 


Return Value 
x The lowercase letter corresponding to the 


argument. Or, the unchanged argument, if it 
is not an uppercase character. 
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_tolower 


_tolower 


Format 


Argument 


Description 


Converts an uppercase character to lowercase. 


#include <ctype.h> 


int _tolower (int character); 


character 
This argument must be an uppercase letter. 


The tolower macro is equivalent to the tolower function except that its 
argument must be an uppercase letter (not lowercase, not EOF). 


As of OpenVMS Version 8.3 and to comply with the C99 ANSI standard and 
X/Open Specification, the _tolower macro by default does not evaluate its 
parameter more than once. It simply calls the tolower function. This avoids side 
effects (such as i++ or function calls) where the user can tell how many times an 
expression is evaluated. 


To keep the older, optimized _tolower macro behavior, compile with /DEFINE=_ 
FAST_TOUPPER. Then, as in previous releases, tolower optimizes the call to 
avoid the overhead of a runtime call. The parameters are checked to determine 
how to calculate the result, thereby creating unwanted side effects. Therefore, 
when compiling with /DEFINE=_FAST_TOUPPER, do not use the tolower 
macro with arguments that contain side-effect operations. For instance, the 
following example will not return the expected result: 


d = tolower (C++); 


Return Value 


x The lowercase letter corresponding to the 
argument. 
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touchwin 


touchwin 
Places the most recently edited version of the specified window on the terminal 
screen. 
Format 
#include <curses.h> 
int touchwin (WINDOW *win); 
Argument 


win 
A pointer to the window. 


Description 


The touchwin function is normally used only to refresh overlapping windows. 
Return Values 


OK Indicates success. 
ERR Indicates an error. 
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toupper 


toupper 
Converts a character to uppercase. 
Format 
#include <ctype.h> 
int toupper (int character); 
Argument 
character 
An object of type int representable as an unsigned char or the value of EOF. For 
any other value, the behavior is undefined. 
Description 


If the argument represents a lowercase letter, and there is a corresponding 
uppercase letter, as defined by character type information in the program locale 
category LC_CTYPE, the corresponding uppercase letter is returned. 


If the argument is not a lowercase character, it is returned unchanged. 


Return Value 
x The uppercase letter corresponding to the 


argument. Or, the unchanged argument, if 
the argument is not a lowercase character. 
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_toupper 


_toupper 


Format 


Argument 


Description 


Converts a lowercase character to uppercase. 


#include <ctype.h> 


int _toupper (int character); 


character 
This argument must be a lowercase letter. 


The toupper macro is equivalent to the toupper function except that its 
argument must be a lowercase letter (not uppercase, not EOF). 


As of OpenVMS Version 8.3 and to comply with the C99 ANSI standard and X 
/Open Specification, the toupper macro by default does not evaluate parameters 
more than once. It simply calls the toupper function. This avoids side effects 
(such as i++ or function calls) where the user can tell how many times an 
expression is evaluated. 


To keep the older, optimized _toupper macro behavior, compile with /DEFINE=_ 
FAST_TOUPPER. Then, as in previous releases, toupper optimizes the call to 
avoid the overhead of a runtime call. The parameters are checked to determine 
how to calculate the result, thereby creating unwanted side effects. So when 
compiling with /DEFINE=_FAST_TOUPPER, do not use the toupper macro 
with arguments that contain side-effect operations. For instance, the following 
example will not return the expected result: 


d = toupper (c++); 


Return Value 
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x The uppercase letter corresponding to the 
argument. 


towctrans 


towctrans 


Format 


Arguments 


Description 


Maps one wide character to another according to a specified mapping descriptor. 


#include <wctype.h> 


wint_t towctrans (wint_t we, wctrans_t desc); 


wc 
The wide character that you want to map. 


desc 
Description of the mapping obtained through a call to the wctrans function. 


The towctrans function maps the wide character specified in wc, using the 
mapping described by desc. 


The current setting of the LC_CTYPE category must be the same as during the call 
to the wctrans function that returned the value of desc. 


Return Value 


x The mapped value of the we wide character, if 
this character exists in the mapping described by 
desc. Otherwise, the value of wc is returned. 
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towlower 


towlower 


Format 


Argument 


Description 
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Converts the argument, a wide-character code, to lowercase. If the argument is 
not an uppercase character, it is returned unchanged. 


#include <wctype.h> (7so ©) 
#include <wchar.h> ~xPG4) 


int towlower (wint_t we); 


wc 
An object of type wint_t representable as a valid wide character in the current 
locale, or the value of WEOF. For any other value, the behavior is undefined. 


If the argument is an uppercase wide character, the corresponding lowercase wide 
character (as defined in the LC_CTYPE category of the locale) is returned, if it 
exists. If it does not exist, the function returns the input argument unchanged. 


towupper 


towupper 


Converts the argument, a wide character, to uppercase. If the argument is not a 
lowercase character, it is returned unchanged. 


Format 
#include <wctype.h> so Cc) 
#include <wchar.h> (xPG4) 
int towupper (wint_t we); 
Argument 
wc 
An object of type wint_t representable as a valid wide character in the current 
locale, or the value of WEOF. For any other value, the behavior is undefined. 
Description 


If the argument is a lowercase wide character, the corresponding uppercase wide 
character (as defined in the LC_CTYPE category of the locale) is returned, if it 
exists. If it does not exist, the function returns the input argument unchanged. 
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truNC (ipha, 164) 


tr unc (Alpha, I64) 


Truncates the argument to an integral value. 


Format 

#include <math.h> 

double trunc (double x); 

float truncf (float x,): 

long double truncl (long double x); 
Argument 


x 
A floating-point number. 


Return Value 


n The truncated, integral value of the argument. 
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truncate 


truncate 


Format 


Arguments 


Description 


Changes file length to a specified length, in bytes. 


#include <unistd.h> 


int truncate (const char “path, off_t length); 


path 

The name of a file that is to be truncated. This argument must point to a 
pathname that names a regular file for which the calling process has write 
permission. 


length 

The new length of the file, in bytes. The off t type of length is either a 64-bit 
or 32-bit integer. The 64-bit interface allows for file sizes greater than 2 GB, and 
can be selected at compile time by defining the LLARGEFILE feature-test macro 
as follows: 


CC/DEFINE= LARGEFILE 


The truncate function changes the length of a file to the size, in bytes, specified 
by the length argument. 


If the new length is less than the previous length, the function removes all 
data beyond length bytes from the specified file. All file data between the new 
End-of-File and the previous End-of-File is discarded. 


For stream files, if the new length is greater than the previous length, new 

file data between the previous End-of-File and the new End-of-File is added, 
consisting of all zeros. (For record files, it is not possible to extend the file in this 
manner.) 


Return Values 


0 Indicates success. 


—1 An error occurred; errno is set to indicate the 
error. 
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ttyname, ttyname_r 


ttyname, ttyname_r 


Format 


Arguments 


Description 
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Find the pathname of a terminal. 


#include §<unixio.h> (Compatability) 

char *ttyname (void); (Compatability) 

#include <unistd.h> (OpenVMS V7.3-2 and higher) 

char “ttyname (int filedes); (OpenVMS V7.3-2 and higher) 


int ttyname_r (int filedes, char name, size_t namesize); (OpenVMS V7.3-2 and higher), (Alpha, 164) 


filedes 
An open file descriptor. 


name 
Pointer to a buffer in which the terminal name is stored. 


namesize 
The length of the buffer pointed to by the name argument. 


The implementation of the ttyname function that takes no argument is provided 
only for backward compatibility. This legacy implementation returns a pointer to 
the null-terminated name of the terminal device associated with file descriptor 0, 
the default input device (stdin). A value of 0 is returned if SYS$INPUT is not a 
TTY device. 


The ttyname_r function and the implementation of ttyname that takes a filedes 
argument are UNIX standard compliant and are available with only OpenVMS 
Version 7.3-2 and higher. 


The standard compliant ttyname function returns a pointer to a string containing 
a null-terminated pathname of the terminal associated with file descriptor filedes. 
The return value might point to static data whose content is overwritten by each 
call. The ttyname interface need not be reentrant. 


The ttyname_r function returns a pointer to store the null-terminated pathname 
of the terminal associated with the file descriptor filedes in the character array 
referenced by name. The array is namesize characters long and should have space 
for the name and the terminating null character. The maximum length of the 
terminal name is TTY NAME MAX. 


If successful, ttyname returns a pointer to a string. Otherwise, a NULL pointer is 
returned and errno is set to indicate the error. 


If successful, ttyname_r stores the terminal name as a null-terminated string 
in the buffer pointed to by name and returns 0. Otherwise, an error number is 
returned to indicate the error. 


Return Values 


NULL 


ttyname, ttyname_r 


Upon successful completion, ttyname returns a 
pointer to a null-terminated string. 


Upon failure, ttyname returns a NULL pointer 
and sets errno to indicate the failure: 


e EBADF - The fildes argument is not a valid 
file descriptor. 


e ENOTTY — The fildes argument does not 
refer to a terminal device. 


Upon successful completion, ttyname_r returns 
0. 

Upon failure, ttyname_r sets errno to indicate 
the failure, and returns the same errno code: 


e EBADF - The fildes argument is not a valid 
file descriptor. 


e ENOTTY — The fildes argument does not 
refer to a TTY device. 


e ERANGE - The value of namesize is smaller 
than the length of the string to be returned 
including the terminating null character. 


For the legacy ttyname, indicates that 
SYS$INPUT is not a TTY device. 


REF-693 


tzset 


tzset 


Format 


Description 
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Sets and accesses time-zone conversion. 


#include <time.h> 
void tzset (void); 
extern char *tzname[]; 
extern long int timezone; 


extern int daylight; 


The tzset function initializes time-conversion information used by the ctime, 
localtime, mktime, strftime, and wcsftime functions. 


The tzset function sets the following external variables: 


e tzname is set as follows, where "std" is a 3-byte name for the standard time 
zone, and "dst" is a 3-byte name for the Daylight Savings Time zone: 


W std" 
"dst" 


tzname [0] 
tzname [1] 


e daylight is set to 0 if Daylight Savings Time should never be applied to the 
time zone. Otherwise, daylight is set to 1. 


e timezone is set to the difference between UTC and local standard time. 


The environment variable TZ specifies how tzset initializes time conversion 
information: 


e If TZ is absent from the environment, the implementation-dependent time- 
zone information is used, as follows: 


The best available approximation to local wall-clock time is used, as 
defined by the SYS$LOCALTIME system logical, which points to a tzfile 
format file that describes default time-zone rules. 

This system logical is set during the installation of OpenVMS Version 

7.0 or higher to define a time-zone file based off the root directory 
SYS$COMMON:|[SYS$ZONEINFO.SYSTEM].! 


e If TZ appears in the environment but its value is a null string, Coordinated 
Universal Time (UTC) is used (without leap-second correction). 


1 The HP C RTL uses a public-domain, time-zone handling package that puts time-zone 


conversion rules in easily accessible and modifiable files. These files reside in the 
SYS$COMMON:[SYS$ZONEINFO.SYSTEM.SOURCES] directory. 

The time-zone compiler zic converts these files to a special format described by 

the <tzfile.h> header file. The converted files are created with a root directory of 
SYS$COMMON:[SYS$ZONEINFO.SYSTEM], which is pointed to by the SYS$TZDIR 
system logical. This format is readable by the C library functions that handle time-zone 
information. For example, in the eastern United Stated, SYS$LOCALTIME is defined to 
be SYS$COMMON: [SYS$ZONEINFO.SYSTEM.US]EASTERN. 


tzset 


e If TZ appears in the environment and its value is not a null string, the value 
has one of three formats, as described in Table REF-11. 


Table REF-11 Time-Zone Initialization Rules 


TZ Format 


Meaning 


:pathname 


stdoffset|dst [offset] 
[,rule]] 


UTC is used. 


The characters following the colon specify the pathname 
of a tzfile format file from which to read the time- 
conversion information. A pathname beginning with a 
slash (/) represents an absolute pathname; otherwise, 
the pathname is relative to the system time-conversion 
information directory specified by SYS$TZDIR, which by 
default is SYS$COMMON:|ISYS$ZONEINFO.SYSTEM]. 


The value is first used as the pathname of a file (as 
described for the :pathname format) from which to read 
the time-conversion information. 


If that file cannot be read, the value is then interpreted as 
a direct specification of the time-conversion information, as 
follows: 


std and dst—Three or more characters that are the 
designation for the time zone: 


e std—Standard time zone. Required. 


e dst—Daylight Savings Time zone. Optional. If dst is 
omitted, Daylight Savings Time does not apply. 


Uppercase and lowercase letters are explicitly allowed. Any 
characters are allowed, except the following: 


e digits 

e leading colon (:) 

¢ comma (,) 

¢ minus (—) 

° plus (+) 

e ASCII null character 


offset—The value added to the local time to arrive at UTC. 
The offset has the following format: 


hh[{:mm[:ss] ] 


In this format: 
e hh (hours) is a one-or two-digit value of 0-24. 
¢ mm (minutes) is a value of 0-59. (optional) 


e ss (seconds) is a value of 0-59. (optional) 


(continued on next page) 
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tzset 
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Table REF-11 (Cont.) Time-Zone Initialization Rules 


TZ Format 


Meaning 


The offset following std is required. If no offset follows 
dst, summer time is assumed, one hour ahead of standard 
time. You can use one or more digits; the value is always 
interpreted as a decimal number. 

If the time zone is preceded by a minus sign (— ), the time 
zone is East of Greenwich; otherwise, it is West, which can 
also be indicated by a preceding plus sign (+). 
rule—Indicates when to change to and return from summer 
time. The rule has the form: 


start[/time], end[/time] 
where: 


e start is the date when the change from standard time to 
summer time occurs. 


e end is the date for returning from summer time to 
standard time. 


If start and end are omitted, the default is the US Daylight 
Savings Time start and end dates. The format for start and 
end must be one of the following: 


e Jn—The Julian day n (1 <n < 365). Leap days are 
not counted. That is, in all years, including leap years, 
February 28 is day 59 and March 1 is day 60. You 
cannot explicitly refer to February 29. 


e n—tThe zero based Julian day (0 <n < 365). Leap days 
are counted, making it possible to refer to February 29. 


e Mm.n.d—The nth d day of month m, where: 


O<n<5d 

0<d<6 

l<m<12 
When n is 5, it refers to the last d day of month m. 
Sunday is day 0. 


(continued on next page) 
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Table REF-11 (Cont.) Time-Zone Initialization Rules 


TZ Format Meaning 


time—The time when, in current time, the change to or 
return from summer time occurs. The time argument has 
the same format as offset, except that you cannot use a 
leading minus (—) or plus (+) sign. If time is not specified, 
the default is 02:00:00. 

If no rule is present in the TZ specification, the rules used 
are those specified by the tzfile format file defined by 
the SYS$POSIXRULES system logical in the system time- 
conversion information directory, with the standard and 
summer time offsets from UTC replaced by those specified 
by the offset values in TZ. 

If TZ does not specify a tzfile format file and cannot be 
interpreted as a direct specification, UTC is used. 


Note 


The UTC-based time functions, introduced in OpenVMS Version 7.0, had 
degraded performance compared with the non-UTC-based time functions. 


OpenVMS Version 7.1 added a cache for time-zone files to improve 
performance. The size of the cache is determined by the logical name 
DECC$TZ_CACHE_SIZE. To accommodate most countries changing the 
time twice per year, the default cache size is large enough to hold two 
time-zone files. 


See also ctime, localtime, mktime, strftime, and wcsftime. 


Sample TZ Specification 
EST5EDT4 ,M4.1.0,M10.5.0 


This sample TZ specification describes the rule defined in 1987 for the 
Eastern time zone in the US: 


e EST (Eastern Standard Time) is the designation for standard time, which 
is 5 hours behind UTC. 


e EDT (Kastern Daylight Time) is the designation for summer time, which 
is 4 hours behind UTC. EDT starts on the first Sunday in April and ends 
on the last Sunday in October. 


Because time was not specified in either case, the changes occur at the default 
time, which is 2:00 A.M. The start and end dates did not need to be specified, 
because they are the defaults. 
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ualarm 


ualarm 


Format 


Arguments 


Description 


Sets or changes the timeout of interval timers. 


#include <unistd.h> 


useconds_t ualarm (useconds_t mseconds, useconds_t interval): 


mseconds 
Specifies a number of real-time microseconds. 


interval 
Specifies the interval for repeating the timer. 


The ualarm function causes the SIGALRM signal to be generated for the calling 
process after the number of real-time microseconds specified by wseconds has 
elapsed. When the interval argument is nonzero, repeated timeout notification 
occurs with a period in microseconds specified by interval. If the notification 
signal SIGALRM is not caught or is ignored, the calling process is terminated. 


If you call a combination of ualarm and setitimer functions, and the AST status 
is disabled, the return value is invalid. 


If you call a combination of ualarm and setitimer functions, and the AST status 
is enabled, the return value is valid. 


This is because you cannot invoke an AST handler to clear the previous value of 
the timer when ASTs are disabled or invoked from a handler that was invoked at 
AST level. 


Note 


Interactions between ualarm and either alarm, or sleep are unspecified. 


See also setitimer. 


Return Values 
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n The number of microseconds remaining from the 
previous ualarm or setitimer call. 

0 No timeouts are pending or ualarm not previously 
called. 

—1 Indicates an error. 


umask 


umask 


Format 


Argument 


Description 


Creates a file protection mask that is used when a new file is created, and returns 
the previous mask value. 


#include <stat.h> 


mode_t umask (mode_t mode_complemeni); 


mode_complement 
Shows which bits to turn off when a new file is created. See the description of 
chmod to determine what the bits represent. 


Initially, the file protection mask is set from the current process’s default 

file protection. This is done when the C main program starts up or when 
DECCSCRTL_INIT (or VAXCSCRTL_INIT) is called. You can change this for all files 
created by your program by calling umask or you can use chmod to change the file 
protection on individual files. The file protection of a file created by open or creat 
is the bitwise AND of the open and creat mode argument with the complement 
of the value passed to umask on the previous call. 


Note 


The way to create files with OpenVMS RMS default protections using 
the UNIX system-call functions umask, mkdir, creat, and open is to 
call mkdir, creat, and open with a file-protection mode argument of 
0777 in a program that never specifically calls umask. These default 
protections include correctly establishing protections based on ACLs, 
previous versions of files, and so on. 


In programs that do vfork/exec calls, the new process image inherits 
whether umask has ever been called or not from the calling process image. 
The umask setting and whether the umask function has ever been called 
are both inherited attributes. 


Return Value 


x The old mask value. 
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uname 


uname 


Format 


Argument 


Description 


Gets system identification information. 


#include <utsname.h> 


int uname (struct utsname *name); 


name 
The current system identifier. 


The uname function stores null-terminated strings of information identifying the 
current system into the structure referenced by the name argument. 


The utsname structure is defined in the <utsname.h> header file and contains the 
following members: 


sysname Name of the operating system implementation 
nodename Network name of this machine 

release Release level of the operating system 

version Version level of the operating system 

machine Machine hardware platform 


Return Values 
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0 Indicates success. 


—1 Indicates an error; errno or vaxcSerrno is set as 
appropriate. 


ungetc 


ungetc 


Format 


Arguments 


Description 


Pushes a character back into the input stream and leaves the stream positioned 
before the character. 


#include <stdio.h> 


int ungetc (int character, FILE *file_ptn); 


character 
A value of type int. 


file_ptr 
A file pointer. 


When using the ungetc function, the character is pushed back onto the file 
indicated by file_ptr. 


One push-back is guaranteed, even if there has been no previous activity on 

the file. The fseek function erases all memory of pushed-back characters. The 
pushed-back character is not written to the underlying file. If the character to be 
pushed back is EOF, the operation fails, the input stream is left unchanged, and 
EOF is returned. 


See also fseek and getc. 


Return Values 


x The push-back character. 
EOF Indicates it cannot push the character back. 
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ungetwc 


ungetwc 

Pushes a wide character back into the input stream. 
Format 

#include <wchar.h> 

wint_t ungetwc (wint_t we, FILE *file_ptr); 
Arguments 

wc 

A value of type wint_t. 

file_ptr 

A file pointer. 
Description 


When using the ungetwc function, the wide character is pushed back onto the file 
indicated by file_ptr. 


One push-back is guaranteed, even if there has been no previous activity on the 
file. If a file positioning function (such as fseek) is called before the pushed back 
character is read, the bytes representing the pushed back character are lost. 


If the character to be pushed back is WEOF, the operation fails, the input stream 
is left unchanged, and WEOF is returned. 


See also getwe. 


Return Values 


x The push-back character. 

WEOF Indicates that the function cannot push the 
character back. errno is set to one of the 
following: 


e EBADF - The file descriptor is not valid. 


e EALREADY — Operation is already in 
progress on the same file. 


e EILSEQ — Invalid wide-character code 
detected. 


REF-702 


unlink (ipna, 164) 


unlink (Alpha, 164) 


Deletes the specified symbolic link from the system. 


Format 
#include <unistd.h> 


int unlink (const char *link_name); 


Arguments 

link_name 

The name of the symbolic link to be deleted. 
Description 


The unlink function deletes the specified symbolic link (ink_name) from the 
system. The contents of the symbolic link are not examined, and no action 
is performed on the file specified in the contents. For other files, the unlink 
function behaves the same as the C RTL remove function. 


See also symlink, readlink, realpath, lchown, and lstat. 


Return Values 


0 Succesful completion. 


-1 Indicates an error. The named file (link_name) is 
unchanged, and errno is set to any errno value 
from remove. 
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unordered (iia, 164) 


unordered (Alpha, 164) 


Returns the value 1 (TRUE) if either or both of the arguments is a NaN. 
Otherwise, it returns the value 0 (FALSE). 


Format 

#include <math.h> 

double unordered (double x, double y); 

float unorderedf (float x, float y); 

long double unorderedl (long double x, long double y); 
Arguments 


x 
A real number. 


y 


A real number. 


Return Values 


Either or both of the arguments is a NaN. 
Neither argument is a NaN. 
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unsetenv 


unsetenv 

Deletes all instances of the environment variable name from the environment list. 
Format 

#include <stdlib.h> 

void unsetenv (const char *name); 
Argument 


name 
The environment variable to delete from the environment list. 


Description 


The unsetenv function deletes all instances of the variable name pointed to by 
the name argument from the environment list. 
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usleep 


usleep 


Format 


Argument 


Description 


Suspends execution for an interval. 


#include <unistd.h> 


int usleep (unsigned int mseconds); 


mseconds 
The number of microseconds to suspend execution for. 


The usleep function suspends the current process from execution for the number 
of microseconds specified by the mseconds argument. This argument must be less 
than 1,000,000. However, if its value is 0, then the call has no effect. 


There is one real-time interval timer for each process. The usleep function does 
not interfere with a previous setting of this timer. If the process set this timer 
before calling usleep and if the time specified by mseconds equals or exceeds the 
interval timer’s prior setting, then the process is awakened shortly before the 
timer was set to expire. 


Return Values 
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0 Indicates success. 


—1 Indicates an error occurred; errno is set to 
EINVAL. 


utime 


utime 


Format 


Arguments 


Description 


Sets file access and modification times. 


#include <utime.h> 


int utime (const char *path, const struct utimbuf *times); 


path 
A pointer to a file. 


times 
A NULL pointer or a pointer to a utimbuf structure. 


The utime function sets the access and modification times of the file named by 
the path argument. 


If times is a NULL pointer, the access and modification times of the file are set 
to the current time. To use utime in this way, the effective user ID of the process 
must match the owner of the file, or the process must have write permission to 
the file or have appropriate privileges. 


If times is not a NULL pointer, it is interpreted as a pointer to a utimbuf 
structure, and the access and modification times are set to the values in the 
specified structure. Only a process with an effective user ID equal to the user ID 
of the file or a process with appropriate privileges can use utime this way. 


The utimbuf structure is defined by the <utime.h> header. The times in the 
utimbuf structure are measured in seconds since the Epoch. 


Upon successful completion, utime marks the time of the last file status change, 
st_ctime, to be updated. See the <stat.h> header file. 


Note (Alpha, 164) 


On OpenVMS Alpha and I64 systems, the stat, fstat, utime, and utimes 
functions have been enhanced to take advantage of the new file-system 
support for POSIX compliant file timestamps. 


This support is available only on ODS-5 devices on OpenVMS Alpha 
systems beginning with a version of OpenVMS Alpha after Version 7.3. 
Before this change, stat and fstat set the values of the st_ctime, 
st_mtime, and st_atime fields based on the following file attributes: 


st_ctime —- ATR$C_CREDATE (file creation time) 

st_mtime —- ATR$C_REVDATE (file revision time) 

st_atime — was always set to st_mtime because no support for file 
access time was available 


Also, for the file-modification time, utime and utimes were modifying 
the ATR$C_REVDATE file attribute, and ignoring the file-access-time 
argument. 
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utime 


After the change, for a file on an ODS-5 device, the stat and fstat 
functions set the values of the st_ctime, st_mtime, and st_atime fields 
based on the following new file attributes: 


st_ctime —- ATR$C_ATTDATE (last attribute modification time) 
st_mtime — ATR$C_MODDATE (last data modification time) 
st_atime - ATR$C_ACCDATE (last access time) 


If ATR$C_ACCDATE is 0, as on an ODS-2 device, the stat and fstat 
functions set st_atime to st_mtime. 


For the file-modification time, the utime and utimes functions modify 
both the ATR$C_REVDATE and ATR$C_MODDATE file attributes. For 
the file-access time, these functions modify the ATR$C_ACCDATE file 
attribute. Setting the ATR$C_MODDATE and ATR$C_ACCDATE file 
attributes on an ODS-2 device has no effect. 


For compatibility, the old behavior of stat, fstat, utime, and utimes 
remains the default, regardless of the kind of device. 

The new behavior must be explicitly enabled by defining the DECC$EFS_ 
FILE_TIMESTAMPS logical name to "ENABLE" before invoking the 


application. Setting this logical does not affect the behavior of stat, 
fstat, utime, and utimes for files on an ODS-2 device. 


Return Values 


0 Successful execution. 


—1 Indicates an error. The function sets errno to 
one of the following values: 


The utime function will fail if: 


e EACCES -— Search permission is denied 
by a component of the path prefix; or the 
times argument is a NULL pointer and the 
effective user ID of the process does not 
match the owner of the file and write access 
is denied. 


e ELOOP — Too many symbolic links were 
encountered in resolving path. 


e ENAMETOOLONG - The length of the path 
argument exceeds PATH_MAX, a pathname 
component is longer than NAME_MAX, or 
a pathname resolution of a symbolic link 
produced an intermediate result whose 
length exceeds PATH_MAX. 


e ENOENT - path does not name an existing 
file, or path is an empty string. 
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utime 


ENOTDIR — A component of the path prefix 
is not a directory. 


EPERM -— times is not a NULL pointer and 
the calling process’s effective user ID has 
write-access to the file but does not match 
the owner of the file, and the calling process 
does not have the appropriate privileges. 


EROFS - The file system containing the file 
is read-only. 
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utimes 


utimes 


Format 


Arguments 


Description 
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Sets file access and modification times. 


#include <time.h> 


int utimes (const char “path, const struct timeval times[2]); 


path 
A pointer to a file. 


times 

an array of timeval structures. The first array member represents the date and 
time of last access, and the second member represents the date and time of last 
modification. The times in the timeval structure are measured in seconds and 
microseconds since the Epoch, although rounding toward the nearest second may 
occur. 


The utimes function sets the access and modification times of the file pointed to 
by the path argument to the value of the times argument. The utimes function 
allows time specifications accurate to the microsecond. 


If the times argument is a NULL pointer, the access and modification times of the 
file are set to the current time. The effective user ID of the process must be the 
same as the owner of the file, or must have write access to the file or appropriate 
privileges to use this call in this manner. 


Upon completion, utimes marks the time of the last file status change, st_ctime, 
for update. 


Note (Alpha, 164) 


On OpenVMS Alpha and I64 systems, the stat, fstat, utime, and utimes 
functions have been enhanced to take advantage of the new file-system 
support for POSIX compliant file timestamps. 


This support is available only on ODS-5 devices on OpenVMS Alpha 
systems beginning with a version of OpenVMS Alpha after Version 7.3. 


Before this change, the stat and fstat functions were setting the values 
of the st_ctime, st_mtime, and st_atime fields based on the following file 
attributes: 


st_ctime - ATR$C_CREDATE (file creation time) 

st_mtime — ATR$C_REVDATE (file revision time) 

st_atime — was always set to st_mtime because no support for file 
access time was available 


Also, for the file-modification time, utime and utimes were modifying 
the ATR$C_REVDATE file attribute, and ignoring the file-access-time 
argument. 


Return Values 


utimes 


After the change, for a file on an ODS-5 device, the stat and fstat 
functions set the values of the st_ctime, st_mtime, and st_atime fields 
based on the following new file attributes: 


st_ctime — ATR$C_ATTDATE (last attribute modification time) 
st_mtime —- ATR$C_MODDATE (last data modification time) 
st_atime — ATR$C_ACCDATE (last access time) 


If ATR$C_ACCDATE is 0, as on an ODS-2 device, the stat and fstat 
functions set st_atime to st_mtime. 


For the file-modification time, the utime and utimes functions modify 
both the ATR$C_REVDATE and ATR$C_MODDATE file attributes. For 
the file-access time, these functions modify the ATR$C_ACCDATE file 
attribute. Setting the ATR$C_MODDATE and ATR$C_ACCDATE file 
attributes on an ODS-2 device has no effect. 


For compatibility, the old behavior of stat, fstat, utime, and utimes 
remains the default, regardless of the kind of device. 

The new behavior must be explicitly enabled by defining the DECC$EFS_ 
FILE_TIMESTAMPS logical name to "ENABLE" before invoking the 


application. Setting this logical does not affect the behavior of stat, 
fstat, utime, and utimes for files on an ODS-2 device. 


Successful execution. 


Indicates an error. The file times do not change 
and the function sets errno to one of the 
following values: 


The utimes function will fail if: 


e EACCES — Search permission is denied 
by a component of the path prefix; or the 
times argument is a NULL pointer and the 
effective user ID of the process does not 
match the owner of the file and write access 
is denied. 


e ELOOP — Too many symbolic links were 
encountered in resolving path. 


e ENAMETOOLONG - The length of the path 
argument exceeds PATH_MAX, a pathname 
component is longer than NAME_MAX, or 
a pathname resolution of a symbolic link 
produced an intermediate result whose 
length exceeds PATH_MAX. 


e ENOENT —- A component of path does not 
name an existing file, or path is an empty 
string. 
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utimes 
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ENOTDIR — A component of the path prefix 
is not a directory. 


EPERM -—The times argument is not a NULL 
pointer and the calling process’s effective 
user ID has write-access to the file but does 
not match the owner of the file and the 
calling process does not have the appropriate 
privileges. 


EROFS -— The file system containing the file 
is read-only. 


VAXCS$CRTL_INIT 


VAXC$CRTL_INIT 


Format 


Description 


Allows you to call the HP C RTL from other languages or to use the HP C RTL 
when your main function is not in C. It initializes the run-time environment and 
establishes both an exit and condition handler. VAXCSCRTL_INIT is a synonym for 
DECCSCRTL_INIT. Hither name invokes the same routine. 


#include <signal.h> 
void VAXC$CRTL_INIT( ); 


The following example shows a Pascal program that calls the HP C RTL using 
the VAXC$CRTL_INIT function: 


On OpenVMS VAX systems: 


$ PASCAL EXAMPLE 
$ LINK EXAMPLE, SYSSLIBRARY : DECCRTL/LIB 
$ TY EXAMPLE. PAS 
PROGRAM TESTC(input, output) ; 
PROCEDURE VAXC$CRTL INIT; extern; 
BEGIN 

VAXCSCRTL_INIT; 
END 
$ 


On OpenVMS Alpha systems: 


$ PASCAL EXAMPLE 
$ LINK EXAMPLE, SYSSLIBRARY : VAXCRTL/LIB 
$ TY EXAMPLE. PAS 
PROGRAM TESTC(input, output) ; 
PROCEDURE VAXC$CRTL INIT; extern; 
BEGIN 

VAXCSCRTL_INIT; 
END 
$ 


A shareable image need only call this function if it contains an HP C function 
for signal handling, environment variables, I/O, exit handling, a default file 
protection mask, or if it is a child process that should inherit context. 


Although many of the initialization activities are performed only once, 
DECCS$CRTL_INIT can safely be called multiple times. On OpenVMS VAX systems, 
DECCS$CRTL_INIT establishes the HP C RTL internal OpenVMS exception handler 
in the frame of the routine that calls DECCS$CRTL_INIT each time DECCSCRTL_INIT 
is called. 


At least one frame in the current call stack must have that handler established 
for OpenVMS exceptions to get mapped to UNIX signals. 
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VAXCS$ESTABLISH 


VAXCS$ESTABLISH 


Format 


Arguments 


Description 
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Used for establishing an OpenVMS exception handler for a particular routine. 
This function establishes a special HP C RTL exception handler in the routine 
that called it. This special handler catches all RTL-related exceptions that occur 
in later routines, and passes on all other exceptions to your handler. 


#include <signal.h> 
void VAXC$ESTABLISH (unsigned int (“exception_handlen)(void *sigarr, void *mecharn\); 


exception_handler 
The name of the function that you want to establish as an OpenVMS exception 
handler. You pass a pointer to this function as the parameter to VAXCSESTABLISH. 


sigarr 
A pointer to the signal array. 


mecharr 
A pointer to the mechanism array. 


VAXCSESTABLISH must be used in place of LIBSESTABLISH when programs use the 
HP C RTL routines setjmp or longjmp. See setjmp and longjmp, or sigsetjmp 
and siglongjmp. 


You can only invoke the VAXCSESTABLISH function from an HP C for OpenVMS 
function, because it relies on the allocation of data space on the run-time stack by 
the HP C compiler. Calling the OpenVMS system library routine LIBSESTABLISH 
directly from an HP C function results in undefined behavior from the set jmp 
and longjmp functions. 


To cause an OpenVMS exception to generate a UNIX style signal, user exception 
handlers must return SS$ RESIGNAL upon receiving any exception that they do 
not want to handle. Returning SS$ NORMAL prevents the generation of a UNIX 
style signal. UNIX signals are generated as if by an exception handler in the 
stack frame of the main C program. Not all OpenVMS exceptions correspond 

to UNIX signals. See Chapter 4 for more information on the interaction of 
OpenVMS exceptions and UNIX style signals. 


Calling VAXCSESTABLISH with an argument of NULL cancels an existing handler 
in that routine. 


Notes 


e On OpenVMS Alpha systems, VAXCSESTABLISH is implemented as a 
compiler built-in function, not as an HP C RTL function. (Alpha only) 


VAXCS$ESTABLISH 


On OpenVMS VAX systems, programs compiled with /NAMES=AS_IS 
should link against SYS$LIBRARY:DECCRTL.OLB to resolve the 
name VAXCSESTABLISH, whether or not the program is compiled with 
the /PREFIX_LIBRARY_ENTRIES switch. This is a restriction in the 
implementation. (VAX only) 
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va_arg 


va_arg 
Returns the next item in the argument list. 


Format 
#include <stdarg.h> (ANSI C) 
#include <varargs.h> (HP C Extension) 


type va_arg (va_list ap, type); 


Arguments 


ap 
A variable list containing the next argument to be obtained. 


type 

A data type that is used to determine the size of the next item in the list. An 
argument list can contain items of varying sizes, but the calling routine must 
determine what type of argument is expected since it cannot be determined at 
run time. 


Description 


The va_arg function interprets the object at the address specified by the list 
incrementor according to type. If there is no corresponding argument, the 
behavior is undefined. 


When using va_arg to write portable applications, include the <stdarg.h> 
header file (defined by the ANSI C standard), not the <varargs.h> header file, 
and use va_arg only in conjunction with other functions and macros defined in 
<stdarg.h>. 


For an example of argument-list processing using the <stdarg.h> functions and 
definitions, see Example 3-6. 
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va_count 


va_count 


Format 


Argument 


Description 


Returns the number of longwords (vax only) or quadwords (Alpha only) in the 
argument list. 


#include <stdarg.h> (ANSI ©) 
#include <varargs.h> (HP C Extension) 


void va_count (int count); 


count 
An integer variable name in which the number of longwords (Vax only) or 
quadwords (Alpha only) is returned. 


The va_count macro places the number of longwords (vax only) or quadwords 
(Alpha only) in the argument list into count. The value returned in count is the 
number of longwords (VAX only) or quadwords (Alpha only) in the function argument 
block not counting the count field itself. 


If the argument list contains items whose storage requirements are a longword 
(VAX only) or quadword (Alpha only) of memory or less, the number in the count 
argument is also the number of arguments. However, if the argument list 
contains items that are longer than a longword (VAX only) or a quadword (Alpha only), 
count must be interpreted to obtain the number of arguments. Because a double 
is 8 bytes, it occupies two argument-list positions on OpenVMS VAX systems, and 
one argument-list position on OpenVMS Alpha and 164 systems. 


The va_count macro is specific to HP C for OpenVMS Systems and is not 
portable. 
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va_end 


va_end 


Format 


Argument 


Description 
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Finishes the <varargs.h> or <stdarg.h> session. 


#include <stdarg.h> (ANSI C) 
#include <varargs.h> (HP C Extension) 


void va_end (va_list ap); 


ap 
The object used to traverse the argument list length. You must declare and use 
the argument ap as shown in this format section. 


You can execute multiple traversals of the argument list, each delimited by 
va_start ...va_end. The va_end function sets ap equal to NULL. 


When using this function to write portable applications, include the <stdarg.h> 
header file (defined by the ANSI C standard), not the <varargs.h> header file, 
and use va_end only in conjunction with other routines defined in <stdarg.h>. 


For an example of argument-list processing using the <stdarg.h> functions and 
definitions, see Example 3-6. 


va_start, va_start_1 


va_start, va_start_1 


Format 


Arguments 


Description 


Used for initializing a variable to the beginning of the argument list. 


#include <varargs.h> (HP C Extension) 
void va_start (va_list ap): 


void va_start_1 (va_list ap, int offset); 


ap 
An object pointer. You must declare and use the argument ap as shown in the 
format section. 


offset 

The number of bytes by which ap is to be incremented so that it points to a 
subsequent argument within the list (that is, not to the start of the argument 
list). Using a nonzero offset can initialize ap to the address of the first of the 
optional arguments that follow a number of fixed arguments. 


The va_start macro initializes the variable ap to the beginning of the argument 
list. 


The va_start_1 macro initializes ap to the address of an argument that is 
preceded by a known number of defined arguments. The printf function is 
an example of a HP C RTL function that contains a variable-length argument 
list offset from the beginning of the entire argument list. The variable-length 
argument list is offset by the address of the formatting string. 


When determining the value of the offset argument used in va_start_1, the 
implications of the OpenVMS calling standard must be considered. 


On OpenVMS VAX, most argument items are a longword. For example, 
OpenVMS VAX arguments of types char and short use a full longword of 
memory when they are present in argument lists. However, OpenVMS VAX 
arguments of type float use two longwords because they are converted to type 
double. 


On OpenVMS Alpha and I64 systems, each argument item is a quadword. 


Note 


When accessing argument lists, especially those passed to a subroutine 
(written in C) by a program written in another programming language, 
consider the implications of the OpenVMS calling standard. For more 
information about the OpenVMS calling standard, see the HP C User’s 
Guide for OpenVMS Systems or the OpenVMS Calling Standard. 


The preceding version of va_start and va_start_1 is specific to the HP C RTL, 
and is not portable. 
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va_start, va_start_1 


Format 


Arguments 


Description 
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The following syntax describes the va_start macro in the <stdarg.h> header file, 
as defined in the ANSI C standard: 


#include <stdarg.h> (ANSI C) 


void va_start (va_list ap, parmN); 


ap 
An object pointer. You must declare and use the argument ap as shown in the 
format section. 


parmN 
The name of the last of the known fixed arguments. 


The pointer ap is initialized to point to the first of the optional arguments that 
follow parmN in the argument list. 


Always use this version of va_start in conjunction with functions that are 
declared and defined with function prototypes. Also use this version of va_start 
to write portable programs. 


For an example of argument-list processing using the <stdarg.h> functions and 
definitions, see Example 3-6. 


vfork 


vfork 


Format 


Description 


Creates an independent child process. This function is nonreentrant. 


#include <unistd.h> 
int vfork (void); (.DECC_V4_SOURCE) 


pid_t vfork (void); (ot _DECC_V4_SOURCE) 


The vfork function provided by HP C for OpenVMS Systems differs from the 
fork function provided by other C implementations. Table REF—12 shows the two 
major differences. 


Table REF-12 The vfork and fork Functions 


The vfork Function The fork Function 

Used with the exec functions. Can be used without an exec function for 
asynchronous processing. 

Creates an independent child Creates an exact duplicate of the parent 

process that shares some of process that branches at the point where 

the parent’s characteristics. vfork is called, as if the parent and the child 
are the same process at different stages of 
execution. 


The vfork function provides the setup necessary for a subsequent call to an exec 
function. Although no process is created by vfork, it performs the following steps: 


e It saves the return address (the address of the vfork call) to be used later as 
the return address for the call to an exec function. 


e It saves the current context. 


e It returns the integer 0 the first time it is called (before the call to an exec 
function is made). After the corresponding exec function call is made, the 
exec function returns control to the parent process, at the point of the vfork 
call, and it returns the process ID of the child as the return value. Unless the 
exec function fails, control appears to return twice from vfork even though 
one call was made to vfork and one call was made to the exec function. 


The behavior of the vfork function is similar to the behavior of the setjmp 
function. Both vfork and setjmp establish a return address for later use, both 
return the integer 0 when they are first called to set up this address, and both 
pass back the second return value as though it were returned by them rather 
than by their corresponding exec or longjmp function calls. 


However, unlike setjmp, with vfork, all local automatic variables, even those 
with volatile-qualified type, can have indeterminate values if they are modified 
between the call to vfork and the corresponding call to an exec routine. 
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vfork 


Return Values 


0 
nonzero 


—1 
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Indicates successful creation of the context. 


Indicates the process ID (PID) of the child 
process. 


Indicates an error — failure to create the child 
process. 


vfprintf 


vfprintf 


Format 


Arguments 


Description 


Prints formatted output based on an argument list. 


#include <stdio.h> 


int vfprintf (FILE *file_ptr, const char *format, va_list ap); 


file_ptr 
A pointer to the file to which the output is directed. 


format 

A pointer to a string containing the format specification. For more information 
about format and conversion specifications and their corresponding arguments, 
see Chapter 2. 


ap 


A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


See also vprintf and vsprintf. 


Return Values 


x The number of bytes written. 

Negative value Indicates an output error. The function sets 
errno. For a list of possible errno values set, see 
fprintf. 
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viscanf 


Format 


Arguments 


Description 


Reads formatted input based on an argument list. 


#include <stdio.h> 


int viscanf (FILE *file_ptr, const char *format, va_list ap); 


file_ptr 
A pointer to the file that provides input text. 


format 
A pointer to a string containing the format specification. 


ap 
A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


The vfscanf function is the same as the fscanf function except that instead of 
being called with a variable number of arguments, it is called with an argument 
list that has been initialized by va_start (and possibly subsequent va_arg calls). 


If no conversion specifications are given, you can omit the input pointers. 
Otherwise, the function calls must have exactly as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


This function returns the number of successfully matched and assigned input 
items. 


See also vscanf and vsscanf. 


Return Values 
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n The number of successfully matched and 
assigned input items. 


EOF 


viscanf 


Indicates that the end-of-file was encountered or 
a read error occurred. If a read error occurs, the 
function sets errno to one of the following: 


EILSEQ — Invalid character detected. 
EINVAL — Insufficient arguments. 


ENOMEM — Not enough memory available 
for conversion. 


ERANGE -— Floating-point calculations 
overflow. 


EVMSERR — Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This can indicate that conversion 
to a numeric value failed due to overflow. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


EBADF — The file descriptor is not valid. 
EIO — I/O error. 

ENXIO — Device does not exist. 

EPIPE — Broken pipe. 


EVMSERR — Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 


REF-725 


vfwprintf 


vfwprintf 
Writes output to the stream under control of the wide-character format string. 
Format 
#include <wchar.h> 
int vfwprintf (FILE *stream, const wchar_t *format, va_list ap); 
Arguments 
stream 
A file pointer. 
format 
A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 
ap 
A variable list of the items needed for output. 
Description 


The vfwprintf function is equivalent to the fwprintf function, with the variable 
argument list replaced by the ap argument. Initialize ap with the va_start 
macro (and possibly with subsequent va_arg calls) from <stdarg.h>. 


If the stream pointed to by stream has no orientation, vfwprintf makes the 
stream wide-oriented. 


See also fwprintf. 
Return Values 


n The number of wide characters written. 
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vfwprintf 


Negative value Indicates an error. The function sets errno to 
one of the following: 


EILSEQ — Invalid character detected. 
EINVAL -— Insufficient arguments. 


ENOMEM — Not enough memory available 
for conversion. 


ERANGE -— Floating-point calculations 
overflow. 


EVMSERR — Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This might indicate that 
conversion to a numeric value failed because 
of overflow. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


Examples 


EBADF — The file descriptor is not valid. 
EIO — I/O error. 


ENOSPC — No free space on the device 
containing the file. 


ENXIO — Device does not exist. 
EPIPE — Broken pipe. 


ESPIPE — Illegal seek in a file opened for 
append. 


EVMSERR — Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 


The following example shows the use of the vfwprintf function in a general 


error reporting routine: 


#include <stdarg.h> 
#include <stdio.h> 
#include <wchar.h> 


void error(char *function_ name, wchar t *format, ... )j; 


va_list args; 


va_start (args, format) ; 


/* print out name of function causing error */ 
fwprintf (stderr, L"ERROR in %s: ", function_name) ; 
/* print out remainder of message */ 

vfwprintf (stderr, format, args); 


va_end(args) ; 
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vfiwscanf 


vfwscanf 


Format 


Arguments 


Description 


Reads input from the stream under control of a wide-character format string. 


#include <wchar.h> 


int viwscanf (FILE “stream, const wchar_t “format, va_list ap); 


stream 
A file pointer. 


format 
A pointer to a wide-character string containing the format specifications. 


ap 
A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


The vfwscanf function is equivalent to the fwscanf function, except that 
instead of being called with a variable number of arguments, it is called with 
an argument list (ap) that has been initialized by va_start (and possibly with 
subsequent va_arg calls). 


If the stream pointed to by stream has no orientation, viwscanf makes the stream 
wide-oriented. 


For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


Return Values 
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n The number of successfully matched and 
assigned wide-character input items. 
EOF Indicates that a read error occurred before any 


conversion. The function sets errno. For a list of 
the values set by this function, see vfscanf. 


vprintf 


vprintf 


Format 


Arguments 


Description 


Prints formatted output based on an argument list. 


This function is the same as the printf function except that instead of being 
called with a variable number of arguments, it is called with an argument list 
that has been initialized by the va_start macro (and possibly with subsequent 
va_arg calls) from <stdarg.h>. 


#include <stdio.h> 


int vprintf (const char *format, va_list ap); 


format 

A pointer to the string containing the format specification. For more information 
about format and conversion specifications and their corresponding arguments, 
see Chapter 2. 


ap 
A variable list of the items needed for output. 


See the vfprintf and vsprintf functions. 


Return Values 


x The number of bytes written. 

Negative value Indicates an output error. The function sets 
errno. For a list of possible errno values set, see 
fprintf. 


REF-729 


vscanf 


vscanf 


Format 


Arguments 


Description 


Reads formatted input based on an argument list. 


#include <stdio.h> 


int vscanf (const char *format, va_list ap); 


format 
A pointer to the string containing the format specification. 


ap 
A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


The vscanf function is the same as the scanf function except that instead of 
being called with a variable number of arguments, it is called with an argument 
list (ap) that has been initialized by the va_start macro (and possibly with 
subsequent va_arg calls). 


For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


See also scanf, vfscanf, and vsscanf. 


Return Values 
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n The number of successfully matched and 
assigned input items. 

EOF Indicates that a read error occurred before any 
conversion. The function sets errno. For a list of 
the values set by this function, see vfscanf. 


vsnprintf (ipro, 164 


vsnprint dip, 162 


Format 


Arguments 


Description 


Prints formatted output based on an argument list. 


#include <stdio.h> 


int vsnprintf (char “str, size_t n, const char *format, va_list ap): 


str 
A pointer to a string that will receive the formatted output. 


format 

A pointer to a character string that contains the format specification. For more 
information about format and conversion specifications and their corresponding 
arguments, see Chapter 2. 


ap 
A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


The vsnprintf function is the same as the snprintf function, but instead of 
being called with a variable number of arguments, it is called with an argument 
list that has been initialized by va_start (and possibly with subsequent va_arg 
calls). 


This function does not invoke the va_end macro. Because the function invokes 
the va_arg macro, the value of ap after the return is unspecified. 


Applications using vsnprintf should call va_end(ap) afterwards to clean up. 


Return Values 


x The number of bytes (excluding the terminating 
null byte) that would be written to str if n is 
sufficiently large. 

Negative value Indicates an output error occurred. The function 
sets errno. For a list of possible errno values 
set, see fprintf. 
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vsprintf 


vsprintf 


Format 


Arguments 


Prints formatted output based on an argument list. 


This function is the same as the sprintf function except that instead of being 
called with a variable number of arguments, it is called with an argument list 
that has been initialized by va_start (and possibly with subsequent va_arg calls). 


#include <stdio.h> 


int vsprintf (char “str, const char “format, va_list ap); 


str 
A pointer to a string that will receive the formatted output. This string is 
assumed to be large enough to hold the output. 


format 

A pointer to a character string that contains the format specification. For more 
information about format and conversion specifications and their corresponding 
arguments, see Chapter 2. 


ap 
A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


Return Value 
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x The number of bytes written. 


Negative value Indicates an output error occurred. The function 
sets errno. For a list of possible errno values 
set, see fprintf. 


vsscanf 


vsscanf 


Format 


Arguments 


Description 


Reads formatted input based on an argument list. 


#include <stdio.h> 


int vsscanf (char “str, const char *format, va_list ap); 


str 
The address of the character string that provides the input text to sscanf. 


format 
A pointer to a character string that contains the format specification. 


ap 
A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


The vsscanf function is the same as the sscanf function except that instead of 
being called with a variable number of arguments, it is called with an argument 
list that has been initialized by va_start (and possibly with subsequent va_arg 
calls). 


The vsscanf function is also equivalent to the vfscanf function, except that the 
first argument specifies a wide-character string rather than a stream. Reaching 
the end of the wide-character string is the same as encountering EOF for the 
vfscanf function. 


For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


See also vsscanf and sscanf. 


Return Values 


n The number of successfully matched and 
assigned input items. 

EOF Indicates that a read error occurred before any 
conversion. The function sets errno. For a list of 
the values set by this function, see vfscanf. 
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vswprintf 


Writes output to the stream under control of the wide-character format string. 


Format 
#include <wchar.h> 


int vswprintf (wchar_t *s, size_t n, const wchar_t *format, va_list ap); 


Arguments 


s 
A pointer to a multibyte character sequence. 


n 
The maximum number of bytes that comprise the multibyte character. 


format 

A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


ap 
A variable list of the items needed for output. 


Description 


The vswprintf function is equivalent to the swprintf function, with the variable 
argument list replaced by the ap argument. Initialize ap with the va_start 
macro, and possibly with subsequent va_arg calls. 


See also swprintf. 


Return Values 


n The number of wide characters written. 
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Negative value 


vswprintf 


Indicates an error. The function sets errno to 
one of the following: 


e EILSEQ - Invalid character detected. 
e EINVAL - Insufficient arguments. 


e ENOMEM — Not enough memory available 
for conversion. 


e ERANGE - Floating-point calculations 
overflow. 


e EVMSERR - Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This might indicate that 
conversion to a numeric value failed because 
of overflow. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


e EBADF - The file descriptor is not valid. 
e EIO— I/O error. 


e ENOSPC — No free space on the device 
containing the file. 


e ENXIO — Device does not exist. 
e EPIPE — Broken pipe. 


e ESPIPE — Illegal seek in a file opened for 
append. 


e EVMSERR -— Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 
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vswscanf 


vswscanf 


Format 


Arguments 


Description 


Reads input from the stream under control of the wide-character format string. 


#include <wchar.h> 


int vswscanf (wchar_t “s, const wchar_t “format, va_list ap); 


s 
A pointer to a wide-character string from which the input is to be obtained. 


format 
A pointer to a wide-character string containing the format specifications. 


ap 
A list of expressions whose results correspond to conversion specifications given 
in the format specification. 


The vswscanf function is equivalent to the swscanf function, except that 
instead of being called with a variable number of arguments, it is called with 
an argument list (ap) that has been initialized by va_start (and possibly with 
subsequent va_arg calls). 


The vswscanf function is also equivalent to the vfwscanf function, except that the 
first argument specifies a wide-character string rather than a stream. Reaching 
the end of the wide-character string is the same as encountering EOF for the 
vfwscanf function. 


For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


See also vfwscanf and swscanf. 


Return Values 
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n The number of wide characters read. 

EOF Indicates that a read error occurred before any 
conversion. The function sets errno. For a list of 
the values set by this function, see vfscanf. 


vwprintf 


vwprintf 


Format 


Arguments 


Description 


Writes output to an array of wide characters under control of the wide-character 
format string. 


#include <wchar.h> 


int vwprintf (const wchar_t *format, va_list ap); 


format 

A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


ap 
The variable list of items needed for output. 


The vwprintf function is equivalent to the wprintf function, with the variable 
argument list replaced by the ap argument. Initialize ap with the va_start 
macro, and possibly with subsequent va_arg calls. The vwprintf function does 
not invoke the va_end macro. 


See also wprintf. 


Return Values 


x The number of wide characters written, not 
counting the terminating null wide character. 

Negative value Indicates an error. Either n or more wide 
characters were requested to be written, or a 


conversion error occurred, in which case errno is 
set to EILSEQ. 
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vwscanf 


vwscanf 


Format 


Arguments 


Description 


Reads input from an array of wide characters under control of a wide-character 
format string. 


#include <wchar.h> 


int vwscanf (const wchar_t *format, va_list ap); 


format 
A pointer to a wide-character string containing the format specifications. 


ap 
A list of expressions whose resultant types correspond to the conversion 
specifications given in the format specifications. 


The vwscanf function is equivalent to the wscanf function, except that instead of 
being called with a variable number of arguments, it is called with an argument 
list (ap) that has been initialized by va_start (and possibly with subsequent 
va_arg calls). 


For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


See also wscanf. 


Return Values 
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n The number of wide characters read. 


EOF Indicates that a read error occurred before any 
conversion. The function sets errno. For a list of 
the values set by this function, see vfscanf. 


wait 


wait 


Format 


Argument 


Description 


Checks the status of the child process before exiting. A child process is 
terminated when the parent process terminates. 


#include <wait.h> 


pid_t wait (int *status): 


status 

The address of a location to receive the final status of the terminated child. The 
child can set the status with the exit function and the parent can retrieve this 
value by specifying status. 


The wait function suspends the parent process until the final status of a 
terminated child is returned from the child. 


On OpenVMS Version 7.0 and higher systems, the wait function is equivalent 

to waitpid( 0, status, 0 ) if you include <wait.h> and compile with the 
_POSIX_EXIT feature-test macro set (either with /DEFINE=_POSIX_EXIT or with 
#define POSIX EXIT at the top of your file, before any file inclusions). 


Return Values 


x The process ID (PID) of the terminated child. If 
more than one child process was created, wait 
will return the PID of the terminated child that 
was most recently created. Subsequent calls will 
return the PID of the next most recently created, 
but terminated, child. 


-1 No child process was spawned. 
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wait3 


wait3 


Format 


Arguments 


Description 
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Waits for a child process to stop or terminate. 


#include <wait.h> 


pid_t wait3 (int “status_location, int options, struct rusage *resource_usage); 


status_location 
A pointer to a location that contains the termination status of the child process as 
defined in the <wait .h> header file. 


Beginning with OpenVMS Version 7.2, when compiled with the _VMS_WAIT 
macro defined, the wait3 function puts the OpenVMS completion code of the child 
process at the address specified in the status_location argument. 


options 
Flags that modify the behavior of the function. These flags are defined in the 
Description section. 


resource_usage 
The location of a structure that contains the resource utilization information for 
terminated child processes. 


The wait3 function suspends the calling process until the request is completed, 
and redefines it so that only the calling thread is suspended. 


The options argument modifies the behavior of the function. You can combine the 
flags for the options argument by specifying their bitwise inclusive OR. The flags 
are: 


WNOWAIT Specifies that the process whose status is returned in 
status_location is kept in a waitable state. You can wait 
for the process again with the same results. 


WNOHANG Prevents the suspension of the calling process. If there 
are child processes that stopped or terminated, one is 
chosen and the waitpid function returns its process ID, 
as when you do not specify the WNOHANG flag. If there are 
no terminated processes (that is, if waitpid suspends 
the calling process without the WNOHANG flag), 0 (zero) 
is returned. Because you can never wait for process 0, 
there is no confusion arising from this return. 


WUNTRACED Specifies that the call return additional information 
when the child processes of the current process 
stop because the child process received a SIGTTIN, 
SIGTTOU, SIGSTOP, or SIGTSTOP signal. 


If the wait3 function returns because the status of a child process is available, the 
process ID of the child process is returned. Information is stored in the location 
pointed to by status_location, if this pointer is not null. 


wait3 


The value stored in the location pointed to by status_location is 0 (zero) only if the 
status is returned from a terminated child process that did one of the following: 


e Returned 0 from the main function. 
e Passed 0 as the status argument to the exit or exit function. 


Regardless of the status_location value, you can define this information using 
the macros defined in the <wait.h> header file, which evaluate to integral 
expressions. In the following macro descriptions, the statws_valwe argument is 
equal to the integer value pointed to by the status_location argument: 


WIFEXITED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that terminated 
normally. 

WEXITSTATUS(status_value) If the value of WIFEXITED(status_value) is 


nonzero, this macro evaluates to the low-order 8 
bits of the status argument that the child process 
passed to the exit or exit function, or to the 
value the child process returned from the main 
function. 


WIFSIGNALED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that terminated due 
to the receipt of a signal that was not caught. 

WTERMS1G(status_value) If the value of WIFSIGNALED(status_value) is 
nonzero, this macro evaluates to the number of 
the signal that caused the termination of the 
child process. 


WIFSTOPPED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that is currently 
stopped. 

WSTOPSIG(status_value) If the value of WIFSTOPPED(status_value) is 


nonzero, this macro evaluates to the number 
of the signal that caused the child process to 
stop. 


WIFCONTINUED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that has continued. 


If the information stored at the location pointed to by status_location was stored 
there by a call to wait3 that specified the WUNTRACED flag, one of the following 
macros evaluates to a nonzero value: 


e WIFEXITED(*status_value) 

e WIFSIGNALED(*status_value) 
e WIFSTOPPED(*status_value) 

e WIFCONTINUED(*status_value) 


If the information stored in the location pointed to by status_location resulted 
from a call to wait3 without the WUNTRACED flag specified, one of the following 
macros evaluates to a nonzero value: 


e = WIFEXITED(*status_value) 
e WIFSIGNALED(*status_value) 
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The wait3 function provides compatibility with BSD systems. The resource_usage 
argument points to a location that contains resource usage information for the 
child processes as defined in the <resource.h> header file. 


If a parent process terminates without waiting for all of its child processes to 
terminate, the remaining child processes is assigned a parent process ID equal to 
the process ID of the init process. 


See also exit, -exit, and init. 


Return Values 
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0 Indicates success. There are no stopped or exited 
child processes, the WNOHANG option is specified. 


x The process_id of the child process. The status of 
a child process is available. 


—1 Indicates an error; errno is set to one of the 
following values: 


e ECHILD - There are no child processes to 
wait for. 


e EINTR — Terminated by receipt of a signal 
caught by the calling process. 


e EFAULT - The status_location or resource_ 
usage argument points to a location outside 
of the address space of the process. 


e EINVAL— The value of the options argument 
is not valid. 


wait4 


wait4 


Format 


Arguments 


Description 


Waits for a child process to stop or terminate. 


#include <wait.h> 


pid_t wait4 (pid_t process_id, union wait *status_location, int options, struct rusage *resource_usage); 


status_location 
A pointer to a location that contains the termination status of the child process as 
defined in the <wait.h> header file. 


Beginning with OpenVMS Version 7.2, when compiled with the _VMS_WAIT 
macro defined, the wait4 function puts the OpenVMS completion code of the child 
process at the address specified in the status_location argument. 


process _id 
The child process or set of child processes. 


options 
Flags that modify the behavior of the function. These flags are defined in the 
Description section. 


resource_usage 
The location of a structure that contains the resource utilization information for 
terminated child processes. 


The wait4 function suspends the calling process until the request is completed. 


The process_id argument allows the calling process to gather status from a 
specific set of child processes, according to the following rules: 


If the process_id is Then status is requested 


Equal to —1 For any child process. In this respect, the waitpid 
function is equivalent to the wait function. 


Greater than 0 For a single child process and specifies the process ID. 


The wait4 function only returns the status of a child process from this set. 


The options argument to the wait4 function modifies the behavior of the function. 
You can combine the flags for the options argument by specifying their bitwise- 
inclusive OR. The flags are: 


WNOWAIT Specifies that the process whose status is returned in 
status_location is kept in a waitable state. You can wait 
for the process again with the same results. 
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WNOHANG Prevents the suspension of the calling process. If there 
are child processes that stopped or terminated, one is 
chosen and the waitpid function returns its process ID, 
as when you do not specify the WNOHANG flag. If there are 
no terminated processes (that is, if waitpid suspends the 
calling process without the WNOHANG flag), 0 is returned. 
Because you can never wait for process 0, there is no 
confusion arising from this return. 


WUNTRACED Specifies that the call return additional information 
when the child processes of the current process 
stop because the child process received a SIGTTIN, 
SIGTTOU, SIGSTOP, or SIGTSTOP signal. 


If the wait4 function returns because the status of a child process is available, the 
process ID of the child process is returned. Information is stored in the location 
pointed to by status_location, if this pointer is not null. 


The value stored in the location pointed to by status_location is 0 only if the 
status is returned from a terminated child process that did one of the following: 


e Returned 0 from the main function. 
e Passed 0 as the status argument to the exit or exit function. 


Regardless of the status_location value, you can define this information using 
the macros defined in the <wait.h> header file, which evaluate to integral 
expressions. In the following macro descriptions, status_value is equal to the 
integer value pointed to by statws_location: 


WIFEXITED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that terminated 
normally. 

WEXITSTATUS(status_value) If the value of WIFEXITED(status_value) is 


nonzero, this macro evaluates to the low-order 8 
bits of the status argument that the child process 
passed to the exit or exit function, or to the 
value the child process returned from the main 
function. 


WIFSIGNALED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that terminated due 
to the receipt of a signal that was not caught. 

WTERMS1G(status_value) If the value of WIFSIGNALED(status_value) is 
nonzero, this macro evaluates to the number of 
the signal that caused the termination of the 
child process. 


WIFSTOPPED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that is currently 
stopped. 

WSTOPSIG(status_value) If the value of WIFSTOPPED(status_value) is 


nonzero, this macro evaluates to the number 
of the signal that caused the child process to 
stop. 


wait4 


WIFCONTINUED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that has continued. 


If the information stored at the location pointed to by status_location was stored 
there by a call to wait4 that specified the WUNTRACED flag, one of the following 
macros evaluates to a nonzero value: 


e WIFEXITED(*status_value) 

e WIFSIGNALED(*status_value) 
e WIFSTOPPED(*status_value) 

e WIFCONTINUED(*status_value) 


If the information stored in the location pointed to by status_location resulted 
from a call to wait4 without the WUNTRACED flag specified, one of the following 
macros evaluates to a nonzero value: 


e = WIFEXITED(*status_value) 
e WIFSIGNALED(*status_value) 


The wait4 function is similar to the wait3 function. However, the wait4 function 
waits for a specific child as indicated by the process_id argument. The resource_ 
usage argument points to a location that contains resource usage information for 
the child processes as defined in the <resource.h> header file. 


See also exit and exit. 
Return Values 


0 Indicates success. There are no stopped or exited 
child processes, the WNOHANG option is specified. 


x The process_id of the child process. The status of 
a child process is available. 

—1 Indicates an error; errno is set to one of the 
following values: 


e ECHILD —- There are no child processes to 
wait for. 


e EINTR — Terminated by receipt of a signal 
caught by the calling process. 


e EFAULT - The status_location or resource_ 
usage argument points to a location outside 
of the address space of the process. 


e EINVAL— The value of the options argument 
is not valid. 
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waitpid 


Format 


Arguments 


Description 
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Waits for a child process to stop or terminate. 


#include <wait.h> 


pid_t waitpid (pid_t process_id, int *status_location, int options); 


process_id 
The child process or set of child processes. 


status_location 
A pointer to a location that contains the termination status of the child process as 
defined in the <wait .h> header file. 


Beginning with OpenVMS Version 7.2, when compiled with the VMS_WAIT 
macro defined, the waitpid function puts the OpenVMS completion code of the 
child process at the address specified in the status_location argument. 


options 
Flags that modify the behavior of the function. These flags are defined in the 
Description section. 


The waitpid function suspends the calling process until the request is completed. 
It is redefined so that only the calling thread is suspended. 


If the process_id argument is —1 and the options argument is 0, the waitpid 
function behaves the same as the wait function. If these arguments have other 
values, the waitpid function is changed as specified by those values. 


The process_id argument allows the calling process to gather status from a 
specific set of child processes, according to the following rules: 


If the process_id is Then status is requested 


Equal to —1 For any child process. In this respect, the waitpid 
function is equivalent to the wait function. 


Greater than 0 For a single child process and specifies the process ID. 


The waitpid function only returns the status of a child process from this set. 


The options argument to the waitpid function modifies the behavior of the 
function. You can combine the flags for the options argument by specifying their 
bitwise-inclusive OR. The flags are: 


WCONTINUED Specifies that the following is reported to the calling 
process: the status of any continued child process 
specified by the process_id argument whose status is 
unreported since it continued. 
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WNOWAIT Specifies that the process whose status is returned in 
status_location is kept in a waitable state. You can wait 
for the process again with the same results. 


WNOHANG Prevents the calling process from being suspended. If 
there are child processes that stopped or terminated, 
one is chosen and waitpid returns its PID, as when 
you do not specify the WNOHANG flag. If there are no 
terminated processes (that is, if waitpid suspends the 
calling process without the WNOHANG flag), 0 (zero) is 
returned. Because you can never wait for process 0, 
there is no confusion arising from this return. 


WUNTRACED Specifies that the call return additional information 
when the child processes of the current process 
stop because the child process received a SIGTTIN, 
SIGTTOU, SIGSTOP, or SIGTSTOP signal. 


If the waitpid function returns because the status of a child process is available, 
the process ID of the child process is returned. Information is stored in the 
location pointed to by status_location, if this pointer is not null. The value stored 
in the location pointed to by status_location is 0 only if the status is returned 
from a terminated child process that did one of the following: 


e Returned 0 from the main function. 
e Passed 0 as the status argument to the exit or exit function. 


Regardless of the value of status_location, you can define this information using 
the macros defined in the <wait.h> header file, which evaluate to integral 
expressions. In the following function descriptions, status_value is equal to the 
integer value pointed to by statws_location: 


WIFEXITED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that terminated 
normally. 

WEXITSTATUS(status_value) If the value of WIFEXITED(status_value) is 


nonzero, this macro evaluates to the low-order 8 
bits of the status argument that the child process 
passed to the exit or exit function, or to the 
value the child process returned from the main 
function. 


WIFSIGNALED(status_value) Evaluates to a nonzero value if status returned 
for a child process that terminated due to the 
receipt of a signal not caught. 

WTERMS1G(status_value) If the value of WIFSIGNALED(status_value) is 
nonzero, this macro evaluates to the number of 
the signal that caused the termination of the 
child process. 

WIFSTOPPED(status_value) Evaluates to a nonzero value if status was 
returned for a child process that is currently 
stopped. 
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WSTOPSIG(status_value) If the value of WIFSTOPPED(status_value) is 
nonzero, this macro evaluates to the number 
of the signal that caused the child process to 
stop. 


WIFCONTINUED(status_value) Evaluates to a nonzero value if status returned 
for a child process that continued. 


If the information stored at the location pointed to by status_location is stored 
there by a call to waitpid that specified the WUNTRACED flag, one of the following 
macros evaluates to a nonzero value: 


e WIFEXITED(*status_value) 

e WIFSIGNALED(*status_value) 
e WIFSTOPPED(*status_value) 

e WIFCONTINUED(*status_value) 


If the information stored in the buffer pointed to by status_location resulted from 
a call to waitpid without the WUNTRACED flag specified, one of the following macros 
evaluates to a nonzero value: 


e WIFEXITED(*status_value) 
e WIFSIGNALED(*status_value) 


If a parent process terminates without waiting for all of its child processes to 
terminate, the remaining child processes is assigned a parent process ID equal to 
the process ID of the init process. 


See also exit, exit, and wait. 


Return Values 
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0 Indicates success. If the WNOHANG option was 
specified, and there are no stopped or exited child 
processes, the waitpid function also returns a 
value of 0. 
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—1 Indicates an error; errno is set to one of the 
following values: 


ECHILD—tThe calling process has no existing 
unwaited-for child processes. The process or 
process group ID specified by the process_id 
argument does not exist or is not a child 
process of the calling process. 


EINTR—tThe function was terminated by 
receipt of a signal. 

If the waitpid function returns because the 
status of a child process is available, the 
process ID of the child is returned to the 
calling process. If they return because a 
signal was caught by the calling process, —1 
is returned. 


EFAULT— The status_location argument 
points to a location outside of the address 
space of the process. 


EINVAL— The value of the options argument 
is not valid. 
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wcrtomb 


Format 


Arguments 


Description 


Converts the wide character to its multibyte character representation. 


#include <wchar.h> 


size_t wertomb (char *s, wchar_t we, mbstate_t *ps); 


Ss 
A pointer to the resulting multibyte character. 


wc 
A wide character. 


ps 
A pointer to the mbstate_t object. Ifa NULL pointer is specified, the function 
uses its internal mbstate_t object. mbstate_t is an opaque datatype intended to 
keep the conversion state for the state-dependent codesets. 


If s is a NULL pointer, the wcrtomb function is equivalent to the call: 
wertomb (buf, L’\0’, ps) 
where buf is an internal buffer. 


If s is not a NULL pointer, the wcrtomb function determines the number of 
bytes needed to represent the multibyte character that corresponds to the wide 
character specified by we (including any shift sequences), and stores the resulting 
bytes in the array whose first element is pointed to by s. At most MB_CUR_ MAX 
bytes are stored. 


If we is a null wide character, a null byte is stored preceded by any shift sequence 
needed to restore the initial shift state. The resulting state described is the initial 
conversion state. 


Return Values 
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n The number of bytes stored in the resulting 
array, including any shift sequences to represent 
the multibyte character. 


—1 Indicates an encoding error. The we argument is 
not a valid wide character. The global errno is 
set to EILSEQ; the conversion state is undefined. 
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Concatenates two wide-character strings. 


Format 
#include <wchar.h> 


wchar_t *wescat (wchar_t *wstr_1, const wchar_t *wstr_2); 


Function Variants 


The wescat function has variants named wescat32 and _wcscaté4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Arguments 


wstr_1, wstr_2 
Pointers to null-terminated wide-character strings. 


Description 


The wcscat function appends the wide-character string wstr_2, including the 
terminating null character, to the end of wstr_1. 


See also wesncat. 
Return Value 


x The first argument, wstr_1, which is assumed to 
be large enough to hold the concatenated result. 


Example 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <string.h> 


/* This program concatenates two wide-character strings using */ 
/* the wescat function, and then manually compares the result */ 
/* to the expected result */ 


#define S1LENGTH 10 
#define S2LENGTH 8 


main () 


BS dew 
int 1; 
wchar_t slbuf [S1LENGTH + S2LENGTH] ; 
wchar_ t s2buf [S2LENGTH] ; 
wchar_t test1[S1LENGTH + S2LENGTH] ; 


/* Initialize the three wide-character strings */ 


if (mbstowcs(slbuf, "abcmnexyz", S1LENGTH) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 
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if (mbstowcs(s2buf, " orthis", S2LENGTH) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


if (mbstowcs(testl, "abcmnexyz orthis", S1LENGTH + S2LENGTH) 
== (size t)-1) { 


perror("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


/* Concatenate slbuf with s2buf, placing the result 


ny 
/* into * slbuf. Then compare slbuf with the expected */ 
/* result in testl. */ 


wescat(slbuf, s2buf) ; 
for (1 = 0; 1 < S1LENGTH + S2LENGTH - 2; i++) { 
/* Check that each character is correct */ 
if (test1[i] != slbuf[i]) { 
printf("Error in wescat\n") ; 
exit (EXIT_FAILURE) ; 


} 


printf ("Concatenated string: <%S>\n", slbuf) ; 


Running the example produces the following result: 


Concatenated string: <abcmnexyz orthis> 
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weschr 


Format 


Scans for a wide character in a specifed wide-character string. 


#include <wchar.h> 


wchar_t *weschr (const wchar_t *wstr, wchar_t wc): 


Function Variants 


Arguments 


Description 


The weschr function has variants named weschr32 and _wcschré4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


wsir 
A pointer to a null-terminated wide-character string. 


wc 
A character of type wchar t. 


The wcschr function returns the address of the first occurrence of a specified 
wide character in a null-terminated wide-character string. The terminating null 
character is considered to be part of the string. 


See also wesrchr. 


Return Values 


Example 


x The address of the first occurrence of the 
specified wide character. 
NULL Indicates that the wide character does not occur 


in the string. 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <string.h> 


#define BUFF SIZE 50 


main () 


int i; 

wchar_t slbuf [BUFF SIZE] ; 

wchar t *status; 

/* Initialize the buffer */ 

if (mbstowcs(slbuf, "abcdefghijkl lkjihgfedcba", BUFF SIZE) 


== (size t)-1) { 
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perror("mbstowcs") ; 
exit (EXIT_FAILURE 


! 
! 


/* This program checks the weschr function by incrementally */ 
/* going through a string that ascends to the middle and */ 
/* then descends towards the end. */ 


for (i = 0; (slbuf[i] != ’\0') && (slbuf[i] != ' '); i++) { 
status = wceschr(slbuf, slbuf[i]); 
/* Check for pointer to leftmost character - test 1. */ 
if (status != &slbuf[i]) { 
printf("Error in weschr\n") ; 
exit (EXIT_FAILURE) ; 


} 


printf ("Program completed successfully\n") ; 


When this example program is run, it produces the following result: 


Program completed successfully 
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wcescmp 


Format 


Arguments 


Description 


Compares two wide-character strings. It returns an integer that indicates if the 
strings are different, and how they differ. 


#include <wchar.h> 


int wcscmp (const wchar_t *wstr_1, const wchar_t *wstr_2); 


wstr_1, wstr_2 
Pointers to null-terminated wide-character strings. 


The wcscmp function compares the wide characters in wstr_1 with those in wstr_2. 
If the characters differ, the function returns: 


e An integer less than 0, if the codepoint of the first differing character in 
wstr_1 is less than the codepoint of the corresponding character in wstr_2 


e An integer greater than 0, if the codepoint of the first differing character in 
wstr_1 is greater than the codepoint of the corresponding character in wstr_2 


If the wide-characters strings are identical, the function returns 0. 


Unlike the wescoll function, the wcscmp function compares the string based on 
the binary value of each wide character. 


See also wesncmp. 


Return Values 


<0 Indicates that wstr_1 is less than wstr_2. 
=0 Indicates that wstr_1 equals wstr_2. 
>0 Indicates that wstr_1 is greater than wstr_2. 
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wcscoll 


Format 


Arguments 


Description 


Compares two wide-character strings and returns an integer that indicates if the 
strings differ, and how they differ. The function uses the collating information in 
the LC_COLLATE category of the current locale to determine how the comparison 
is performed. 


#include <wchar.h> 


int wescoll (const wchar_t *ws1, const wchar_t *ws2); 


ws1, ws2 
Pointers to wide-character strings. 


The wcscoll function, unlike wcscmp, compares two strings in a locale-dependent 
manner. Because no value is reserved for error indication, the application must 
check for one by setting errno to 0 before the function call and testing it after the 
call. 


See also wcsxfrm. 


Return Values 
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<0 Indicates that ws1 is less than ws2. 
0 Indicates that the strings are equal. 
>0 Indicates that ws1 is greater than ws2. 
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wescpy 


Format 


Copies the wide-character string source, including the terminating null character, 
into dest. 


#include <wchar.h> 


wchar_t *wescpy (wchar_t “dest, const wchar_t *source): 


Function Variants 


Arguments 


Description 


The wcscpy function has variants named wcscpy32 and wcescpyé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


dest 
Pointer to the null-terminated wide-character destination string. 


source 
Pointer to the null-terminated wide-character source string. 


The wescpy function copies source into dest, and stops after copying source’s null 
character. If copying takes place between two ovelapping strings, the behavior is 
undefined. 


See also wesncpy. 


Return Value 


x The address of source. 
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wescspn 


Format 


Arguments 


Description 


Compares the characters in a wide-character string against a set of wide 
characters. The function returns the length of the initial substring that is 
comprised entirely of characters that are not in the set of wide characters. 


#include <wchar.h> 


size_t wescspn (const wchar_t *wsir7, const wchar_t *wstr2); 


wstr1 
A pointer to a null-terminated wide-character string. If this is a null string, 0 is 
returned. 


wstr2 
A pointer to a null-terminated wide-character string that contains the set of wide 
characters for which the function will search. 


The wcscspn function scans the wide characters in the string pointed to by wstr1 
until it encounters a character found in wstr2. The function returns the length of 
the initial segment of wstr1 that is formed by characters not found in wstr2. 


Return Value 


Example 
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x The length of the segment. 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <string.h> 


/* This test sets up 2 strings, buffer and w string, and */ 
/* then uses wescspn() to calculate the maximum segment */ 
/* of w_string, which consists entirely of characters */ 
/* NOT from buffer. */ 


#define BUFF SIZE 20 
#define STRING SIZE 50 


main () 


wchar_t buffer [BUFF SIZE] ; 
wchar_t w_string[STRING SIZE] ; 
size_t result; 


/* Initialize the buffer */ 


if (mbstowcs (buffer, "abcdefg", BUFF SIZE) == (size t)-1) { 


perror("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


/* Initialize the string */ 


wescspn 


if (mbstowcs(w string, "jklmabcjklabcdehjklmno", STRING SIZE) 
== (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE 


} 


/* Using wescspn - work out the largest string in w_string */ 
/* which consists entirely of characters NOT from buffer */ 


result = wescspn(w string, buffer) ; 
printf ("Longest segment NOT found in w_string is: %d", result); 


} 
Running the example program produces the following result: 


Longest segment NOT found in w_string is: 4 
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wesftime 


Format 


Uses date and time information stored in a tm structure to create a wide-character 
output string. The format of the output string is controlled by a format string. 


#include <wchar.h> 
size_t wesftime (wchar_t *wcs, size_t maxsize, const char *format, const struct tm *timeptr); xPaa 


size_t wesftime (wchar_t *wcs, size_t maxsize, const wchar_t *format, const struct tm *timeptr); so c) 


Function Variants 


Arguments 


Description 
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Compiling with the DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test 
macros defined enables a local-time-based entry point to the wcsftime function 
that is equivalent to the behavior before OpenVMS Version 7.0. 


wcs 
A pointer to the resultant wide-character string. 


maxsize 
The maximum number of wide characters to be stored in the resultant string. 


format 

A pointer to the string that controls the format of the output string. For the 
XPG4 interface, this argument is a pointer to a constant character string. For the 
ISO C interface, it is a pointer to a constant wide-character string. 


timeptr 
A pointer to the local time structure. The tm structure is defined in the <time.h> 
header file. 


The wcsftime function uses data in the structure pointed to by timeptr to 
create the wide-character string pointed to by wcs. A maximum of maxsize wide 
characters is copied to wes. 


The format string consists of zero or more conversion specifications and ordinary 
characters. All ordinary characters (including the terminating null character) are 
copied unchanged into the output string. A conversion specification defines how 
data in the tm structure is formatted in the output string. 


A conversion specification consists of a percent (%) character followed by one or 
more optional characters (see Table REF—13), and ending with a conversion 
specifier (see Table REF—14). If any of the optional characters listed in 

Table REF-13 are specified, they must appear in the order shown in the table. 
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Table REF-13 Optional Elements of wesftime Conversion Specifications 


Element Meaning 

- Optional with the field width to specify that the field is left-justified 
and padded with spaces. This cannot be used with the 0 element. 

0 Optional with the field width to specify that the field is right- 
justified and padded with zeros. This cannot be used with the — 
element. 

field width A decimal integer that specifies the maximum field width 

.-precision A decimal integer that specifies the precision of data in a field. 


For the d, H, I, j, m, M, o, S, U, w, W, y, and Y conversion 
specifiers, the precision specifier is the minimum number of digits 
to appear in the field. If the conversion specification has fewer 
digits than that specified by the precision, leading zeros are added. 
For the a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and 

% conversion specifiers, the precision specifier is the maximum 
number of wide characters to appear in the field. If the conversion 
specification has more characters than that specified by the 
precision, characters are truncated on the right. 

The default precision for the d, H, I, m, M, 0, S, U, w, W, y, 
and Y conversion specifiers is 2, and the default precision for the j 
conversion specifier is 3. 


Note that the list of optional elements of conversion specifications from 
Table REF—13 are HP extensions to the XPG4 specification. 


Table REF—14 lists the conversion specifiers. The wcsftime function uses fields 
in the LC_TIME category of the program’s current locale to provide a value. For 
example, if $B is specified, the function accesses the mon field in LC_TIME to find 
the full month name for the month specified in the tm structure. The result of 
using invalid conversion specifiers is undefined. 


Table REF-14 wesftime Conversion Specifiers 


Specifier Replaced by 

a The locale’s abbreviated weekday name. 

A The locale’s full weekday name. 

b The locale’s abbreviated month name. 

B The locale’s full month name. 

Cc The locale’s appropriate date and time representation. 

c The century number (the year divided by 100 and truncated to an 
integer) as a decimal number (00 — 99). 

d The day of the month as a decimal number (01 — 31). 

D Same as %m/%d/%y. 
The day of the month as a decimal number (1 — 31) in a 2-digit 
field with the leading space character fill. 

Ec The locale’s alternative date and time representation. 


(continued on next page) 
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Table REF-14 (Cont.) wesftime Conversion Specifiers 


Specifier Replaced by 

EC The name of the base year (period) in the locale’s alternative 
representation. 

EX The locale’s alternative date representation. 

Ey The offset from the base year (%EC) in the locale’s alternative 
representation. 

EY The locale’s full alternative year representation. 

h Same as %b. 

H The hour (24-hour clock) as a decimal number (00 — 28). 

I The hour (12-hour clock) as a decimal number (01 — 12). 

5 The day of the year as a decimal number (001 — 366). 

m The month as a decimal number (01 — 12). 

M The minute as a decimal number (00 — 59). 

n The new-line character. 

Od The day of the month using the locale’s alternative numeric 
symbols. 

Oe The date of the month using the locale’s alternative numeric 
symbols. 

OH The hour (24-hour clock) using the locale’s alternative numeric 
symbols. 

OI The hour (12-hour clock) using the locale’s alternative numeric 
symbols. 

Om The month using the locale’s alternative numeric symbols. 

OM The minutes using the locale’s alternative numeric symbols. 

os The seconds using the locale’s alternative numeric symbols. 

Ou The weekday as a number in the locale’s alternative representation 
(Monday=1). 

OU The week number of the year (Sunday as the first day of the week) 
using the locale’s alternative numeric symbols. 

OV The week number of the year (Monday as the first day of the 
week) as a decimal number (01 —53) using the locale’s alterntative 
numeric symbols. If the week containing January 1 has four or 
more days in the new year, it is considered as week 1. Otherwise, 
it is considered as week 53 of the previous year, and the next week 
is week 1. 

Ow The weekday as a number (Sunday=0) using the locale’s alternative 
numeric symbols. 

OW The week number of the year (Monday as the first day of the week) 
using the locale’s alternative numeric symbols. 

Oy The year without the century using the locale’s alternative numeric 


symbols. 
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Table REF-14 (Cont.) wecesftime Conversion Specifiers 


Specifier Replaced by 

p The locale’s equivalent of the AM/PM designations associated with 
a 12-hour clock. 

ca The time in AM/PM notation. 

R The time in 24-hour notation (%H: %M). 

S The second as a decimal number (00 — 61). 

t The tab character. 

T The time (%H: $M: %S). 

u The weekday as a decimal number between 1 and 7 (Monday=1). 

U The week number of the year (the first Sunday as the first day of 
week 1) as a decimal number (00 — 53). 

V The week number of the year (Monday as the first day of the week) 
as a decimal number (00 — 53). If the week containing January 1 
has four or more days in the new year, it is considered as week 1. 
Otherwise, it is considered as week 53 of the previous year, and the 
next week is week 1. 

WwW The weekday as a decimal number (0 [Sunday] — 6). 

W The week number of the year (the first Monday as the first day of 
week 1) as a decimal number (00 — 53). 

x The locale’s appropriate date representation 

xX The locale’s appropriate time representation 

y The year without century as a decimal number (00 — 99). 

Y The year with century as a decimal number. 

Z Time-zone name or abbreviation. If time-zone information is not 


oe 


available, no character is output. 
Literal % character. 


Return Values 


x The number of wide characters placed into 
the array pointed to by wes, not including the 
terminating null character. 

0 Indicates an error occurred. The contents of the 
array are indeterminate. 

Example 
/* Exercise the wesftime formatting routine. */ 
/* NOTE: the format string ig an "L" (or wide character) */ 
/* string indicating that this call is NOT in */ 
/* the XPG4 format, but rather in ISO C format. */ 

#include <stdlib.h> 

#include <stdio.h> 

#include <time.h> 

#include <wchar.h> 

#include <locale.h> 

#include <errno.h> 
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#define NUM OF DATES 7 


#define BUF SIZE 256 


/* This program formats a number of different dates, once using the 
Date and time */ 


/* C locale and then using the fr FR.1S08859-1 locale. 


/* formatting is done using wcsftime(). 


main () 


{ 


int count, 
1 ‘ 


wchar_t buffer [BUF_SIZE] ; 


struct tm *tm ptr; 


time t time list [NUM_OF DATES] = 
{500, 68200000, 694223999, 
694224000, 704900000, 705000000, 


705900000}; 


/* Display dates using the C locale */ 
printf ("\nUsing the C locale:\n\n"); 


setlocale(LC ALL, "C"); 


for (i = 0; i < NUM_OF DATES; i++) { 
/* Convert to a tm structure */ 
localtime(&time list [i]); 


tm ptr = 


/* Format the date and time */ 


count = wesftime(buffer, BUF SIZE, L"Date: %A 


if (count 


) 


tm_ptr) ; 


perror ("wesftime") ; 
exit (EXIT_FAILURE) ; 


/* Print the result * 


printf ("%S", buffer) ; 


} 


/* Display dates using the fr FR.1IS08859-1 locale */ 
printf ("\nUsing the fr_FR.1S08859-1 locale:\n\n") ; 


setlocale(LC_ALL, "fr _FR.1S08859-1") ; 
< NUM_OF DATES; i++) { 


for (i = 0; i 


/* Convert to a 


tm ptr = 


tm structure */ 


localtime(&time list [i]); 


/* Format the date and time */ 


count = wesftime 


if (count 


) 


tm_ptr) ; 


perror ("wesftime") ; 
exit (EXIT_FAILURE) ; 


/* Print the result */ 


printf ("%S", buffer) ; 
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d %B tY%nTime: % 


buffer, BUF SIZE, L"Date: %A %d %B %YonTime: % 


a 
xf 


Running the example program produces the following result: 


Using the C locale: 


Date: 
Time: 


Date: 
Time: 


Thursday 01 January 1970 
00:08:20 


Tuesday 29 February 1972 
08:26:40 


: Tuesday 31 December 1991 
223759559 


: Wednesday 01 January 1992 
: 00:00:00 

: Sunday 03 May 1992 

: 13:33:20 

: Monday 04 May 1992 

: 17:20:00 


: Friday 15 May 1992 
: 03:20:00 


the fr FR.1S08859-1 locale: 


: jeudi 01 janvier 1970 
: 00:08:20 


: mardi 29 février 1972 

: 08:26:40 

: mardi 31 décembre 1991 
323359359 

: Mercredi 01 janvier 1992 
: 00:00:00 

: dimanche 03 mai 1992 

: 13:33:20 


: lundi 04 mai 1992 
¢ £72000 


: vendredi 15 mai 1992 
: 03:20:00 


wesftime 
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weslen 


weslen 
Returns the number of wide characters in a wide-character string. The returned 
length does not include the terminating null character. 
Format 
#include <wchar.h> 
size_t weslen (const wchar_t *wstr); 
Argument 


wsir 
A pointer to a null-terminated wide-character string. 


Return Value 


x The length of the wide-character string, 
excluding the terminating null wide character. 
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wcsncat 


wcsncat 


Format 


Concatenates a counted number of wide-characters from one string to another. 


#include <wchar.h> 


wchar_t *wesncat (wchar_t *wstr_1, const wchar_t *wstr_2, size_t maxchan); 


Function Variants 


Arguments 


Description 


The wcesncat function has variants named wcsncat32 and wcsncaté4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


wstr_1, wstr_2 
Pointers to null-terminated wide-character strings. 


maxchar 
The maximum number of wide characters from wstr_2 that are copied to wstr_1. 
If maxchar is 0, no characters are copied from wstr_2. 


The wcsncat function appends wide characters from the wide-character string 
wstr_2 to the end of wstr_1, up to a maximum of maxchar characters. A 
terminating null wide character is always appended to the result of the wesncat 
function. Therefore, the maximum number of wide characters that can end up in 
wstr_1 is wcslen(wstr_1) + maxchar + 1). 


See also wescat. 


Return Value 


Example 


x The first argument, wstr_1, which is assumed to 
be large enough to hold the concatenated result. 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <string.h> 


/* This program concatenates two wide-character strings using */ 
/* the wesncat function, and then manually compares the result */ 
/* to the expected result */ 


#define S1LENGTH 10 
#define S2LENGTH 8 
#define SIZE 3 
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wcsncat 


main () 


Poems 
int 1; 
wchar_t slbuf [S1LENGTH + S2LENGTH] ; 
wchar_ t s2buf [S2LENGTH] ; 
wchar_ t test1[S1LENGTH + S2LENGTH] ; 


/* Initialize the three wide-character strings */ 


if (mbstowcs(slbuf, "abcmnexyz", S1LENGTH) == (size t)-1) { 


perror("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


if (mbstowcs(s2buf, " orthis", S2LENGTH) == (size t)-1) { 


perror("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


if (mbstowcs(testl, "“abcmnexyz orthis", S1LENGTH + SIZE) 
== (size t)-1) { 


perror("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


/* Concatenate slbuf with SIZE characters from s2buf, */ 
/* placing the result into slbuf. Then compare slbuf */ 
/* with the expected result in testl. */ 


wesncat (slbuf, s2buf, SIZE); 


for (1 = 0; 1 <= S1LENGTH + SIZE - 2; i++) { 
/* Check that each character is correct */ 
if (test1[i] != slbuf[i]) { 
printf("Error in wesncat\n") ; 
exit (EXIT_FAILURE) ; 


} 


printf ("Concatenated string: <%S>\n", slbuf) ; 


Running the example produces the following result: 


Concatenated string: <abcmnexyz or> 
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wesncemp 


wesncmp 


Format 


Arguments 


Description 


Compares not more than maxchar characters of two wide-character strings. It 
returns an integer that indicates if the strings are different, and how they differ. 


#include <wchar.h> 


int wesncmp_ (const wchar_t *wstr_1, const wchar_t “wstr_2, size_t maxchan); 


wstr_1, wstr_2 
Pointers to null-terminated wide-character strings. 


maxchar 

The maximum number of characters to search in both wstr_1 and wstr_2. If 
maxchar is 0, no comparison is performed and 0 is returned (the strings are 
considered equal). 


The strings are compared until a null character is encountered, the strings differ, 
or maxchar is reached. If characters differ, wcsncmp returns: 


e An integer less than 0 if the codepoint of the first differing character in wstr_1 
is less than the codepoint of the corresponding character in wstr_2 


e An integer greater than 0 if the codepoint of the first differing character in 
wstr_1 is greater than the codepoint of the corresponding character in wstr_2 


If no differences are found after comparing maxchar characters, the function 
returns 0. 


See also wescmp. 


Return Values 


<0 Indicates that wstr_1 is less than wstr_2. 
0 Indicates that wstr_1 equals wstr_2. 
>0 Indicates that wstr_1 is greater than wstr_2. 
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wesncpy 


wesncpy 


Format 


Copies wide characters from source into dest. The function copies up to a 
maximum of maxchar characters. 


#include <wchar.h> 


wchar_t *wesncpy (wchar_t “dest, const wchar_t “source, size_t maxchar); 


Function Variants 


Arguments 


Description 


The wcsncpy function has variants named wcsncpy32 and wcsncpy64 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


dest 
Pointer to the null-terminated wide-character destination string. 


source 
Pointer to the null-terminated wide-character source string. 


maxchar 
The maximum number of wide characters to copy from source to dest. 


The wcsnepy function copies no more than maxchar characters from source to 
dest. If source contains less than maxchar characters, null characters are added 
to dest until maxchar characters have been written to dest. 


If source contains maxchar or more characters, as many characters as possible 
are copied to dest. The null terminator of sowrce is not copied to dest. 


See also wescpy. 


Return Value 
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x The address of dest. 


wcspbrk 


wespbrk 


Format 


Searches a wide-character string for the first occurrence of one of a specified set 
of wide characters. 


#include <wchar.h> 


wchar_t *wespbrk (const wchar_t *wstr, const wchar_t *charset); 


Function Variants 


Arguments 


Description 


The wespbrk function has variants named wcspbrk32 and wcspbrké64 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


wstr 
A pointer to a wide-character string. If this is a null string, NULL is returned. 


charset 
A pointer to a wide-character string containing the set of wide characters for 
which the function will search. 


The wespbrk function scans the wide characters in the string, stops when it 
encounters a wide character found in charset, and returns the address of the first 
character in the string that appears in the character set. 


Return Values 


x The address of the first wide character in the 
string that is in the set. 

NULL Indicates that none of the characters are in 
charset. 
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wesrchr 


wesrchr 


Format 


Scans for the last occurrence of a wide character in a given string. 


#include <wchar.h> 


wchar_t *wesrchr (const wchar_t *wstr, wchar_t we); 


Function Variants 


Arguments 


Description 


The wcsrchr function has variants named wcsrchr32 and wcsrchré4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


wstr 
A pointer to a null-terminated wide-character string. 


wc 
A character of type wchar t. 


The wcesrchr function returns the address of the last occurrence of a given wide 
character in a null-terminated wide-character string. The terminating null 
character is considered to be part of the string. 


See also weschr. 


Return Values 


Example 
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x The address of the last occurrence of the specified 
wide character. 
NULL Indicates that the wide character does not occur 


in the string. 


include <stdlib.h> 
include <stdio.h> 
include <wchar.h> 
include <string.h> 


define BUFF SIZE 50 
define STRING SIZE 6 


main () 


int i; 

wchar_t slbuf [BUFF SIZE], 
w_string [STRING SIZE] ; 

wchar t *status; 

wchar_t *pbuf = slbuf; 


/* Initialize the buffer */ 
if (mbstowcs(slbuf, "hijklabcdefg ytuhijklfedcba", BUFF SIZE) 


wesrchr 


== (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


} 


/* Initialize the string to be searched for */ 


if (mbstowcs(w string, "hijkl", STRING SIZE) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


/* This program checks the wesrchr function by searching for */ 
/* the last occurrence of a string in the buffer slbuf and */ 
/* prints out the contents of slbuff from the location of 

/* the string found. */ 


status = wesrchr(slbuf, w_string[0]); 
/* Check for pointer to start of rightmost character string. */ 
if (status == pbuf) 
printf("Error in wesrchr\n") ; 
exit (EXIT_FAILURE) ; 


printf ("Program completed successfully\n") ; 
printf ("String found : [%S]\n", status) ; 


} 


Running the example produces the following result: 


Program completed successfully 
String found : [hijklfedcba] 
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wesrtombs 


wcsrtombs 


Format 


Converts a sequence of wide characters into a sequence of corresponding 
multibyte characters. 


#include <wchar.h> 


size_t wesrtombs (char “dst, const wchar_t *“src, size_t len, mbstate_t *ps); 


Function Variants 


Arguments 


Description 
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The wcesrtombs function has variants named wcsrtombs32 and _wcsrtombsé4 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


dst 
A pointer to the destination array for converted multibyte character sequence. 


src 
An address of the pointer to an array containing the sequence of wide characters 
to be converted. 


len 
The maximum number of bytes that can be stored in the array pointed to by dst. 


ps 
A pointer to the mbstate_t object. If a NULL pointer is specified, the function 
uses its internal mbstate_t object. mbstate _t is an opaque datatype intended to 
keep the conversion state for the state-dependent codesets. 


The wcsrtombs function converts a sequence of wide characters from the array 
indirectly pointed to by src into a sequence of corresponding multibyte characters, 
beginning in the conversion state described by the object pointed to by ps. 


If dst is a not a NULL pointer, the converted characters are then stored into the 
array pointed to by dst. Conversion continues up to and including a terminating 
null wide character, which is also stored. 


Conversion stops earlier in two cases: 


e When a code is reached that does not correspond to a valid multibyte 
character 


e If dst is not a NULL pointer, when the next multibyte character would exceed 
the limit of len total bytes to be stored into the array pointed to by dst 


Each conversion takes place as if by a call to the wcrtomb function. 


If dst is not a NULL pointer, the pointer object pointed to by src is assigned either 
a NULL pointer (if the conversion stopped because it reached a terminating null 
wide character) or the address just beyond the last wide character converted (if 
any). If conversion stopped because it reached a terminating null wide character, 
the resulting state described is the initial conversion state. 


wcsrtombs 


If the wcsrtombs function is called as a counting function, which means that 
dst is a NULL pointer, the value of the internal mbstate_t object will remain 
unchanged. 


See also wertomb. 
Return Values 


x The number of bytes stored in the resulting 
array, not including the terminating null (if any). 


—1 Indicates an encoding error—a character that 
does not correspond to a valid multibyte 
character was encountered; errno is set to 
EILSEQ; the conversion state is undefined. 
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wesspn 


wesspn 


Format 


Arguments 


Description 


Compares the characters in a wide-character string against a set of wide 
characters. The function returns the length of the first substring comprised 
entirely of characters in the set of wide characters. 


#include <wchar.h> 


size_t wcsspn (const wchar_t *wsir1, const wchar_t *wstr2); 


wstr1 
A pointer to a null-terminated wide-character string. If this string is a null 
string, 0 is returned. 


wstr2 
A pointer to a null-terminated wide-character string that contains the set of wide 
characters for which the function will search. 


The wcsspn function scans the wide characters in the wide-character string 
pointed to by wstr1 until it encounters a character not found in wstr2. The 
function returns the length of the first segment of wstr1 formed by characters 
found in wstr2. 


Return Value 


Example 
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x The length of the segment. 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <string.h> 


/* This test sets up 2 strings, buffer and w string. It */ 
/* then uses wesspn() to calculate the maximum segment */ 
/* of w_string that consists entirely of characters */ 
/* from buffer. */ 


#define BUFF SIZE 20 
#define STRING SIZE 50 


main () 
wchar_t buffer [BUFF SIZE] ; 
wchar_t w_string[STRING SIZE] ; 
size_t result; 


/* Initialize the buffer */ 


if (mbstowcs (buffer, "abcdefg", BUFF SIZE) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


wesspn 


/* Initialize the string */ 
if (mbstowcs(w string, "abcedjklmabcjklabcdehjk1", STRING SIZE) 
== (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE 


/* Using wesspn - work out the largest string in w string */ 
/* that consists entirely of characters from buffer */ 


result = wcesspn(w string, buffer) ; 
printf ("Longest segment found in w string is: %d", result); 


} 


Running the example program produces the following result: 


Longest segment found in w string is: 5 
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wcesstr 


wesstr 


Locates the first occurrence in the string pointed to by s1 of the sequence of wide 
characters in the string pointed to by s2. 

Format 
#include <wchar.h> 


wchar_t *wesstr (const wchar_t *s7, const wchar_t *s2); 


Function Variants 


The wcsstr function has variants named wecsstr32 and _wesstré4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


Arguments 


s1, s2 
Pointers to null-terminated, wide-character strings. 


Description 


If s2 points to a wide-character string of 0 length, the wcsstr function returns s/. 
Return Values 


x A pointer to the located string. 
NULL Indicates an error; the string was not found. 
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wcstod 


wcstod 


Format 


Arguments 


Description 


Converts a given wide-character string to a double-precision number. 


#include <wchar.h> 


double westod (const wchar_t *nptr, wchar_t **endptr); 


npir 
A pointer to the wide-character string to be converted to a double-precision 
number. 


endpir 

The address of an object where the function can store the address of the first 
unrecognized wide character that terminates the scan. If endptr is a NULL 
pointer, the address of the first unrecognized wide character is not retained. 


The wcstod function recognizes an optional sequence of white-space characters 
(as defined by iswspace), then an optional plus or minus sign, then a sequence 
of digits optionally containing a radix character, then an optional letter (e or E) 
followed by an optionally signed integer. The first unrecognized character ends 
the conversion. 


The string is interpreted by the same rules used to interpret floating constants. 


The radix character is defined in the program’s current locale (category 
LC_NUMERIC). 


This function returns the converted value. For wcstod, overflows are accounted 
for in the following manner: 


e Ifthe correct value causes an overflow, HUGE_VAL (with a plus or minus sign 
according to the sign of the value) is returned and errno is set to ERANGE. 


e If the correct value causes an underflow, 0 is returned and errno is set to 
ERANGE. 


If the string starts with an unrecognized wide character, *endptr is set to nptr 
and a 0 value is returned. 


Return Values 


x The converted string. 
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wcstod 


REF-780 


+HUGE_VAL 


Indicates the conversion could not be performed. 
The function sets errno to one of: 


e EINVAL — No conversion could be performed. 


e ERANGE - The value would cause an 
underflow. 


e ENOMEM — Not enough memory available 
for internal conversion buffer. 


Overflow occurred; errno is set to ERANGE. 


westok 


wcestok 


Format 


Locates text tokens in a given wide-character string. 


#include <wchar.h> 
wchar_t *westok (wchar_t *ws1, const wchar_t “ws2); (xPG4) 


wchar_t “westok (wchar_t *ws7, const wchar_t “ws2, wchar_t **ptr); aso c) 


Function Variants 


Arguments 


Description 


The westok function has variants named _wcestok32 and _wcstoké4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


ws1 
A pointer to a wide-character string containing zero or more text tokens. 


ws2 
A pointer to a separator string consisting of one or more wide characters. The 
separator string can differ from call to call. 


pir 

ISO C Standard only. Used only when ws1 is NULL, pir is a caller-provided 
wchar_t pointer into which wcstok stores information necessary for it to continue 
scanning the same wide-character string. 


A sequence of calls to wcstok breaks the wide-character string pointed to by ws1 
into a sequence of tokens, each of which is delimited by a wide character from the 
wide-character string pointed to by ws2. 


The wcstok function keeps track of its position in the wide-character string 
between calls and, as successive calls are made, the function works through the 
wide-character string, identifying the text token following the one identified by 
the previous call. 


Tokens in ws are delimited by null characters that wcstok inserts into ws1. 
Therefore, ws cannot be a const object. 


The following sections describe differences between the XPG4 Standard and 
ISO C Standard interface to westok. 


XPG4 Standard Behavior 


The first call to the wcstok function searches the wide-character string for the 
first character that is not found in the separator string pointed to by ws2. The 
first call returns a pointer to the first wide character in the first token and writes 
a null wide character into ws1 immediately following the returned token. 
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westok 


Subsequent calls to wcstok search for a wide character that is in the separator 
string pointed to by ws2. Each subsequent call (with the value of the first 
argument remaining NULL) returns a pointer to the next token in the string 
originally pointed to by ws1. When no tokens remain in the string, wcstok 
returns a NULL pointer. 


ISO C Standard Behavior 

For the first call in the sequence, ws1 points to a wide-character string. In 
subsequent calls for the same string, ws1 is NULL. When ws is NULL, the 
value pointed to by ptr matches that stored by the previous call for the same 
wide-character string. Otherwise, the value pointed to by pir is ignored. 


The first call in the sequence searches the wide-character string pointed to by 
ws1 for the first wide character that is not contained in the current separator 
wide-character string pointed to by ws2. If no such wide character is found, then 
there are no tokens in the wide-character string pointed to by ws1, and wcstok 
returns a NULL pointer. 


The wcestok function then searches from there for a wide character that is 
contained in the current separator wide-character string. If no such wide 
character is found, the current token extends to the end of the wide-character 
string pointed to by ws1, and subsequent searches in the same wide-character 
string for a token return a NULL pointer. If such a wide character is found, it is 
overwritten by a null wide character, which terminates the current token. 


In all cases, wcstok stores sufficient information in the pointer pointed to by ptr 
so that subsequent calls with a NULL pointer for ws1 and the unmodified pointer 
value for pir start searching just past the element overwritten by a null wide 
character (if any). 


Return Values 


Examples 


REF-782 


x A pointer to the first character of a token. 
NULL Indicates that no token was found. 


/* XPG4 version of westok call */ 


#include <wchar.h> 
#include <string.h> 
#include <stdio.h> 


main () 
wchar t str[] = L"...ab..cd,,ef.hi"; 
printf ("|%S|\n", westok(str, L".") 


(a ( ) 
printf ("|%S|\n", westok(NULL, L",") 
printf ("|%S/\n", westok(NULL, L",. 
printf ("|%S|\n", westok(NULL, L",. 


westok 


/* ISO C version of westok call */ 
#include <wchar.h> 
#include <string.h> 
#include <stdio.h> 
main () 
{ 
wchar_t str[] = L"...ab..cd,,ef.hi"; 


wchar t *savptr 


printf ("|%s|\n", 
printf ("|%S|\n", 
printf ("/%S|\n", 
printf ("/%S|\n", 


NULL; 

westok(str, L".", &savptr)); 
westok(NULL, L",", &savptr)); 
westok(NULL, L",.", &savptr)); 
westok(NULL, L",.", &savptr)); 


Running this example produces the following results: 


§ $ RUN WCSTOK EXAMPLE 
ab | 
.cd| 
ef 
hi 
$ 
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westol 


westol 


Format 


Converts a wide-character string in a specified base to a long integer value. 


#include <wchar.h> 


long int westol (const wchar_t *nptr, wchar_t **endptr, int base); 


Function Variants 


Arguments 


Description 
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The westol function has variants named westol32 and _wcstolé4 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


nptr 
A pointer to the wide-character string to be converted to a long integer. 


endptr 

The address of an object where the function can store a pointer to the first 
unrecognized character encountered in the conversion process (the character that 
follows the last character processed in the string being converted). If endpir is a 
NULL pointer, the address of the first unrecognized character is not retained. 


base 
The value, 2 through 36, to use as the base for the conversion. 


If base is 16, leading zeros after the optional sign are ignored, and Ox or OX is 
ignored. 


If base is 0, the sequence of characters is interpreted by the same rules used to 
interpret an integer constant. After the optional sign: 


e A leading 0 indicates octal conversion. 
e A leading Ox or 0X indicates hexadecimal conversion. 


e Any other combination of leading characters indicates decimal conversion. 


The westol function recognizes strings in various formats, depending on the value 
of the base. This function ignores any leading white-space characters (as defined 
by the iswspace function) in the given string. It recognizes an optional plus or 
minus sign, then a sequence of digits or letters that can represent an integer 
constant according to the value of the base. The first unrecognized character ends 
the conversion. 


westol 


Return Values 


The converted value. 


0 Indicates that the string starts with an 
unrecognized wide character or that the value 
for base is invalid. If the string starts with an 
unrecognized wide character, *endptr is set to 
nptr. The function sets errno to EINVAL. 


LONG_MAX or LONG_MIN Indicates that the converted value would cause 
a positive or negative overflow, respectively. The 
function sets errno to ERANGE. 
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wcstombs 


wcstombs 


Format 


Arguments 


Description 


Converts a sequence of wide-character codes to a sequence of multibyte 
characters. 


#include <stdlib.h> 


size_t westombs (char “s, const wchar_t *pwes, size_t n): 


Ss 
A pointer to the array containing the resulting multibyte characters. 


pwcs 
A pointer to the array containing the sequence of wide-character codes. 


n 
The maximum number of bytes to be stored in the array pointed to by s. 


The wcstombs function converts a sequence of codes corresponding to multibyte 
characters from the array pointed to by pwcs to a sequence of multibyte 
characters that are stored into the array pointed to by s, up to a maximum 

of n bytes. The value returned is equal to the number of characters converted or 
a —1 if an error occurred. 


This function is affected by the LC_CTYPE category of the program’s current 
locale. 


If s is NULL, this function call is a counting operation and n is ignored. 


See also wctomb. 


Return Values 
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x The number of bytes stored in s, not including 
the null terminating byte. If s is NULL, 
wcstombs returns the number of bytes required 
for the multibyte character array. 


(size_t) -1 Indicates an error occurred. The function sets 
errno to EILSEQ — invalid character sequence, 
or a wide-character code does not correspond to a 
valid character. 


westoul 


wcstoul 


Format 


Converts the initial portion of the wide-character string pointed to by nptr to an 
unsigned long integer. 


#include <wchar.h> 


unsigned long int westoul (const wchar_t *nptr, wchar_t **endptr, int base); 


Function Variants 


Arguments 


Description 


The wcstoul function has variants named wcstoul32 and wcstoulé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


nptr 
A pointer to the wide-character string to be converted to an unsigned long. 


endptr 

The address of an object where the function can store the address of the first 
unrecognized character encountered in the conversion process (the character that 
follows the last character in the string being converted). If endptr is a NULL 
pointer, the address of the first unrecognized character is not retained. 


base 
The value, 2 through 36, to use as the base for the conversion. 


If base is 16, leading zeros after the optional sign are ignored, and Ox or 0X is 
ignored. 


If base is 0, the sequence of characters is interpreted by the same rules used to 
interpret an integer constant: after the optional sign, a leading 0 indicates octal 
conversion, a leading Ox or 0X indicates hexadecimal conversion, and any other 
combination of leading characters indicates decimal conversion. 


The wcestoul function recognizes strings in various formats, depending on the 
value of the base. It ignores any leading white-space characters (as defined by 
the iswspace function) in the string. It recognizes an optional plus or minus 
sign, then a sequence of digits or letters that may represent an integer constant 
according to the value of the base. The first unrecognized wide character ends the 
conversion. 
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Return Values 


x The converted value. 


0 Indicates that the string starts with an 
unrecognized wide character or that the value 
for base is invalid. If the string starts with an 
unrecognized wide character, *endptr is set to 
nptr. The function sets errno to EINVAL. 


ULONG_MAX Indicates that the converted value would 
cause an overflow. The function sets errno to 


ERANGE. 


Example 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 
#include <errno.h> 
#include <limits.h> 


/* This test calls westoul() to convert a string to an */ 
/* unsigned long integer. wcstoul outputs the resulting */ 
/* integer and any characters that could not be converted. */ 


#define MAX STRING 128 


main () 


{ 


int base = 10, 
errno; 

char *input_string = "1234.56"; 
wchar_t string _array [MAX STRING], 

*ptr; 
size t size; 
unsigned long int val; 
printf ("base = [%d]\n", base); 
printf ("String to convert = %s\n", input string); 
if ((size = mbstowcs(string array, input_string, MAX STRING)) == 


(size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


printf ("wchar t string is = [%S]\n", string array) ; 
errno = 0; 
val = westoul(string_ array, &ptr, base) ; 
if (errno == 0) 
printf ("returned unsigned long int from westoul = [%u]\n", val); 
printf ("wide char terminating scan(ptr) = [%S]\n\n", ptr); 


if (errno == ERANGE) { 
perror("error value is :"); 
printf ("ULONG MAX = [su] \n", ULONG_MAX) ; 
printf ("westoul failed, val = [%d]\n\n", val); 
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Running the example program produces the following result: 


base = [10] 

String to convert = 1234.56 

wchar_t string is = [1234.56] 

returned unsigned long int from wcstoul = [1234] 
wide char terminating scan(ptr) = [.56] 
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wcswcs 


Locates the first occurrence in the string pointed to by wstr1 of the sequence of 
wide characters in the string pointed to by wstr2. 

Format 
#include <wchar.h> 


wchar_t *wcswes_ (const wchar_t *wstr7, const wchar_t *wstr2); 


Function Variants 
The weswcs function has variants named _wcswcs32 and wcswcs64 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 

Arguments 
wstr1, wstr2 


Pointers to null-terminated wide-character strings. 


Return Values 


Pointer A pointer to the located wide-character string. 
NULL Indicates that the wide-character string was not 
found. 


Example 


#include <stdlib.h> 
#include <stdio.h> 
#include <wchar.h> 


/* This test uses wcswes() to find the occurrence of each */ 
/* subwide-character string, stringl and string2, within */ 
/* the main wide-character string, lookin. */ 


#define BUF SIZE 50 


main () 
{ 
static char lookin[] = "that this is a test was at the end"; 
char stringl[] = "this", 
string2[] = "the end"; 


wchar_t buffer [BUF SIZE], 
input_buffer [BUF SIZE]; 


/* Convert lookin to wide-character format. */ 
/* Buffer and print it out. */ 
if (mbstowcs (buffer, lookin, BUF SIZE) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


printf ("Buffer to look in: %S\n", buffer) ; 


/* Convert stringl to wide-character format and use */ 
/* weswes() to locate it within buffer */ 
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wcswcs 


if (mbstowcs (input buffer, stringl, BUF SIZE) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT FAILURE) ; 


printf ("this: %S\n", wceswes(buffer, input buffer) ) ; 

/* Convert string2 to wide-character format and use */ 

/* weswes() to locate it within buffer */ 

if (mbstowcs (input buffer, string2, BUF SIZE) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT_FAILURE) ; 


printf ("the end: %S\n", weswes(buffer, input _buffer)) ; 
exit (1) ; 


Running this example produces the following results: 


Buffer to look in: that this is a test was at the end 


this: 


this is a test was at the end 


the end: the end 
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wcswidth 


Format 


Arguments 


Description 


Determines the number of printing positions on a display device that are required 
for a wide-character string. 


#include <wchar.h> 


int weswidth (const wchar_t *pwes, size_t n); 


pwcs 
A pointer to a wide-character string. 


n 
The maximum number of characters in the string. 


The wcswidth function returns the number of printing positions required to 
display the first n characters of the string pointed to by pwes. If there are less 
than n wide characters in the string, the function returns the number of positions 
required for the whole string. 


Return Values 
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The number of printing positions required. 
0 If pwes is a null character. 


—1 Indicates that one (or more) of the wide 
characters in the string pointed to by pwes is 
not a printable character. 


wesxfrm 


wcsxfrm 


Format 


Arguments 


Description 


Changes a wide-character string such that the changed string can be passed to 
the wcscmp function and produce the same result as passing the unchanged string 
to the wcescoll function. 


#include <wchar.h> 


size_t wesxfrm (wchar_t *ws?, const wchar_t *ws2, size_t maxchar); 


ws1, ws2 
Pointers to wide-character strings. 


maxchar 
The maximum number of wide characters, including the null wide-character 
terminator, allowed to be stored in s/. 


The wcsxfrm function transforms the string pointed to by ws2 and stores the 
resulting string in the array pointed to by ws1. No more than maxchar wide 
characters, including the null wide terminator, are placed into the array pointed 
to by ws. 


If the value of maxchar is less than the required size to store the transformed 
string (including the terminating null), the contents of the array pointed to 
by ws1 is indeterminate. In such a case, the function returns the size of the 
transformed string. 


If maxchar is 0, then, ws1 is allowed to be a NULL pointer, and the function 
returns the required size of the ws1 array before making the transformation. 


The wide-character string comparison functions, wcscoll and wcscmp, can produce 
different results given the same two wide-character strings to compare. This is 
because wcescmp does a straightforward comparison of the code point values of the 
characters in the strings, whereas wcscoll uses the locale information to do the 
comparison. Depending on the locale, the wcscoll comparison can be a multipass 
operation, which is slower than wcscmp. 


The wcesxfrm function transforms wide-character strings in such a way that if you 
pass two transformed strings to the wcscmp function, the result is the same as 
passing the two original strings to the wcscoll function. The wcsxfrm function 

is useful in applications that need to do a large number of comparisons on the 
same wide-character strings using wcscoll. In this case, it may be more efficient 
(depending on the locale) to transform the strings once using wcsxfrm and then 
use the wcscmp function to do comparisons. 
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Return Values 


x Length of the resulting string pointed to by ws/, 
not including the terminating null character. 

(size_t) -1 Indicates that an error occurred. The function 
sets errno to EINVAL — The string pointed to by 
ws2 contains characters outside the domain of 
the collating sequence. 


Example 


#include <wchar.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <locale.h> 


/* 
/* 
/* 
/* 


This program verifies that two transformed strings, */ 
when passed through wcesxfrm and then compared, provide */ 
the same result as if passed through wescoll without */ 
any transformation. */ 


#define BUFF SIZE 20 


main () 


{ 


wchar_t w_stringl 
wehar_t w_string2 
wchar_ t w_string3 
wchar_t w_string4 
int errno; 

int coll result; 
int wescmp result; 
size t wcesxfrm_resultl; 
size t wosxfrm_result2; 


BUFF SIZE 
BUFF SIZE 
BUFF SIZE 
BUFF SIZE 


' 
' 
I 
' 


/* setlocale to French locale */ 


if (setlocale(LC_ALL, "fr FR.1S08859-1") == NULL) { 
perror("setlocale") ; 
exit (EXIT FAILURE) ; 


/* Convert each of the strings into wide-character format. */ 


if (mbstowcs(w_stringl, "<a'>bcd", BUFF SIZE) == (size t)-1) { 


perror ("mbstowcs") ; 
exit (EXIT FAILURE) ; 


if (mbstowcs(w string2, "abcz", BUFF SIZE) == (size_t) -1) { 


perror ("mbstowcs") ; 
exit (EXIT FAILURE) ; 


/* Collate string 1 and string 2 and store the result. */ 


errno = 0; 
coll result = wescoll(w_stringl, w_string2) ; 
if (errno) { 

perror ("wescoll") ; 

exit (EXIT FAILURE) ; 


else { 
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/* Transform the strings (using wcsxfrm) into */ 
/* w_string3 and w_string4. */ 


wesxfrm_resultl = wcsxfrm(w_string3, w_stringl, BUFF SIZE) ; 


if (wcsxfrm_resultl == ((size_t) - 1)) 
perror ("wesxfrm") ; 

else if (wcesxfrm_resultl > BUFF SIZE) { 
perror("\n** String is too long **\n"); 
exit (EXIT FAILURE) ; 


else { 
wesxfrm_result2 = wcsxfrm(w_string4, w_string2, BUFF SIZE) ; 
if (wesxfrm_result2 == ((size_t) - 1)) 


perror ("wesxfrm") ; 
exit (EXIT_FAILURE) ; 


else if (wcsxfrm_result2 > BUFF_SIZE) { 
perror("\n** String is too long **\n"); 
exit (EXIT_FAILURE) ; 


/* Compare the two transformed strings and verify that */ 
/* the result is the same as the result from wcescoll on */ 


/* the original strings. * / 
else { 
wescmp result = wescmp(w_string3, w_string4) ; 
if (wescmp result == 0 && (coll_result == 0)) { 


printf ("\nReturn value from wcscoll() and return value" 
" from wcescmp() are both zero."); 
printf("\nThe program was successful\n\n") ; 
else if ((wcscmp result < 0) && (coll_result < 0)) { 

printf ("\nReturn value from wcscoll() and return value" 
"from wescmp() are less than zero."); 
printf("\nThe program was successful\n\n") ; 


else if ((wcscmp result > 0) && (coll_result > 0)) { 

printf ("\nReturn value from wcscoll() and return value" 
"from wcescmp() are greater than zero."); 
printf ("\nThe program was successful\n\n") ; 


} 


else { 
printf ("** Error **\n"); 
printf ("\nReturn values are not of the same type"); 


Running the example program produces the following result: 


Return value from wcscoll() and return value 
from wcescmp() are less than zero. 
The program was successful 


REF-795 


wctob 


wctob 


Format 


Argument 


Description 


Determines if a wide character corresponds to a single-byte multibyte character 
and returns its multibyte character representation. 


#include <stdio.h> 
#include <wchar.h> 


int wctob (wint_t c); 


c 
The wide character to be converted to a single-byte multibyte character. 


The wctob function determines whether the specified wide character corresponds 
to a single-byte multibyte character when in the initial shift state and, if so, 
returns its multibyte character representation. 


Return Values 
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x The single-byte representation of the wide 
character specified. 


EOF Indicates an error. The wide character specified 


does not correspond to a single-byte multibyte 
character. 


wctomb 


wctomb 


Format 


Arguments 


Description 


Converts a wide character to its multibyte character representation. 


#include <stdlib.h> 


int wctomb (char *s, wchar_t wchar); 


s 
A pointer to the resulting multibyte character. 


wchar 
The code for the wide character. 


The wctomb function converts the wide character specified by wchar to its 
multibyte character representation. If s is NULL, then 0 is returned. Otherwise, 
the number of bytes comprising the multibyte character is returned. At most, 
MB_CUR_MAX bytes are stored in the array object pointed to by s. 


This function is affected by the LC_CTYPE category of the program’s current 
locale. 


Return Values 


x The number of bytes comprising the multibyte 
character corresponding to wehar. 

0 If s is NULL. 

-1 If wehar is not a valid character. 
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wctrans 


Returns the description of a mapping, corresponding to specified property, that 
can later be used in a call to towctrans. 

Format 
#include <wctype.h> 


wetrans_t wetrans (const char *property); 


Argument 
property 
The name of the mapping. The following property names are defined for all 
locales: 
e "toupper" 
e "tolower" 


Additional property names may also be defined in the LC_CTYPE category of the 
current locale. 


Description 


The wctrans function constructs a value with type wctrans_t that describes a 
mapping between wide characters identified by the property argument. 


See also towctrans. 


Return Values 


nonzero According to the LC_CTYPE category of the 
current program locale, the string specified as 
a property argument is the name of an existing 
character mapping. The value returned can be 
used in a call to the towctrans function. 


0 Indicates an error. The property argument does 
not identify a character mapping in the current 
program’s locale. 
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wctype 


Format 


Argument 


Description 


Used for defining a character class. The value returned by this function is used 
in calls to the iswctype function. 


#include <wctype.h> so Cc) 
#include <wchar.h> (xPG4) 


wctype_t wctype (const char *char_class); 


char_class 
A pointer to a valid character class name. 


The wctype function converts a valid character class defined for the current locale 
to an object of type wctype t. The following character class names are defined for 
all locales: 


alnum entrl lower space 
alpha digit print upper 
blank graph punct xdigit 


Additional character class names may also be defined in the LC_CTYPE category 
of the current locale. 


See also iswctype. 


Return Values 


Example 


x An object of type wctype_t that can be used in 
calls to the iswctype function. 

0 If the character class name is not valid for the 
current locale. 


#include <locale.h> 
#include <wchar.h> 
#include <stdlib.h> 
#include <stdio.h> 
#include <string.h> 
#include <ctype.h> 


/* This test will set up a number of character class using wctype() */ 
/* and then verify whether calls to iswctype() using these classes */ 
/* produce the same results as calls to the is**** routines. */ 


main () 


wchar_t w_char; 
wctype t ret_val; 


char *character = "A"; 


/* Convert character to wide character format - w_char */ 
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if (mbtowc(&w char, character, 1) == -1) { 
perror ("mbtowc") ; 
exit (EXIT_FAILURE) ; 


/* Check if results from iswalnum() matches check on */ 
/* alnum character class */ 


if ((iswalnum((wint_t) w_char)) && 
(iswetype((wint_t) w char, wetype("alnum") ))) 
printf ("[%C] is a member of the character class alnum\n", w_char); 
else 
printf ("[%C] is not a member of the character class alnum\n", w char); 


/* Check if results from iswalpha() matches check on */ 
/* alpha character class */ 


if ((iswalpha((wint_t) w_char)) && 
(iswcetype((wint_t) w char, wctype("alpha")))) 
printf ("[%C] is a member of the character class alpha\n", w char); 
else 
printf("[%C] is not a member of the character class alpha\n", w char); 


/* Check if results from iswentrl() matches check on */ 
/* cntrl character class */ 


if ((iswentrl((wint_t) w_char)) && 

(iswetype((wint_t) w char, wetype("cntrl")))) 

printf ("[%C] is a member of the character class cntrl\n", w char); 
else 
printf ("[%C] is not a member of the character class cntrl\n", w char); 


/* Check if results from iswdigit() matches check on */ 
/* digit character class */ 


if ((iswdigit((wint_t) w_char)) && 

(iswetype((wint_t) w char, wctype("digit")))) 

printf ("[%C] is a member of the character class digit\n", w char); 
else 
printf ("[%C] is not a member of the character class digit\n", w char); 


/* Check if results from iswgraph() matches check on */ 
/* graph character class */ 


if ((iswgraph((wint_t) w_char)) && 

(iswetype((wint_t) w char, wetype("graph") ) )) 

printf ("[%C] is a member of the character class graph\n", w char); 
else 
printf ("[%C] is not a member of the character class graph\n", w_char) ; 


/* Check if results from iswlower() matches check on */ 
/* lower character class */ 


if ((iswlower((wint_t) w_char)) && 

(iswetype((wint_t) w char, wetype("lower") ))) 

printf ("[%C] is a member of the character class lower\n", w_char) ; 
else 
printf ("[%C] is not a member of the character class lower\n", w char); 


/* Check if results from iswprint() matches check on */ 
/* print character class */ 


if ((iswprint((wint_t) w_char)) && 

(iswetype((wint_t) w char, wctype("print")))) 

printf ("[%C] is a member of the character class print\n", w char) ; 
else 
printf ("[%C] is not a member of the character class print\n", w char); 


/* Check if results from iswpunct() matches check on */ 
/* punct character class */ 
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if ((iswpunct 
(iswctype 
printf ("[ 

else 

printf ("(%C] i 


/* Check if res 
/* space charac 


( 
( 
Cc 


oe —~ —~ 


if ((iswspace 
(iswctype 
printf ("[% 

else 

printf ("(%C] is 


/* Check if res 
/* upper charac 


( 
( 
Cc 


if ((iswupper ( 
( 


( 

(iswctype ( ( 

printf ("[SC 
else 

printf ("[%C] is 


/* Check if res 
/* xdigit chara 


if ((iswxdigit 
(iswctype ( 
printf ("[% 

else 

printf ("[%C] i 


( 
( 
C 


Run: 


PrPrrrrrrrrey 


wctype 


wint_t) w_char)) && 
wint t) w char, wctype("punct") ) )) 
is a member of the character class punct\n", w char); 


Ss not a member of the character class punct\n", w char); 


ults from iswspace() matches check on */ 
ter class */ 


wint_t) w_char)) && 
wint_t) w char, wctype("space") ))) 
is a member of the character class space\n", w char); 


not a member of the character class space\n", w char) ; 


ults from iswupper() matches check on */ 
ter class */ 


wint_t) w_char)) && 
wint_t) w char, wctype("upper") )) ) 
is a member of the character class upper\n", w char); 


not a member of the character class upper\n", w_char) ; 


ults from iswxdigit() matches check on */ 
cter class */ 


(wint_t) wchar)) && 

wint_t) w char, wctype("xdigit") )) ) 

] is a member of the character class xdigit\n", w_char) ; 
Ss not a member of the character class xdigit\n", w char); 


ning this example produces the following result: 


the 
the 
of 
of 
the 
of 
the 
of 
of 
the 
the 


character class alnum 
character class alpha 
the character class cntrl 
the character class digit 
character class graph 
the character class lower 
character class print 
the character class punct 
the character class space 
character class upper 
character class xdigit 


ember of 
ember of 
a member 
a member 
ember of 
a member 
ember of 
a member 
a member 
ember of 
ember of 


is 
is 
is 
is 
is 
is 
is 
is 
is 
is 
is 


a 
an 
no 
no 
an 
no 
an 
no 
no 
an 
an 
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wewidth 


Format 


Argument 


Description 


Determines the number of printing positions on a display device required for the 
specified wide character. 


#include <wchar.h> 


int wewidth (wchar_t we); 


wc 
A wide character. 


The wcwidth function determines the number of column positions needed for the 
specified wide character we. The value of we must be a valid wide character in 
the current locale. 


Return Values 
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The number of printing positions required for we. 
0 If we is a null character. 


-1 Indicates that we does not represent a valid 
printing wide character. 


wmemchr 


wmemchr 


Format 


Locates the first occurrence of a specified wide character in an array of wide 
characters. 


#include <wchar.h> 


wchar_t wmemchr (const wchar_t “s, wchar_t c, size_t n); 


Function Variants 


Arguments 


Description 


The wmemchr function has variants named wmemchr32 and wmemchré4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


s 
A pointer to an array of wide characters to be searched. 


Cc 
The wide character value to search for. 


n 
The maximum number of wide characters in the array to be searched. 


The wmemchr function locates the first occurrence of the specified wide character 
in the initial n wide characters of the array pointed to by s. 


Return Values 


x A pointer to the first occurrence of the wide 
character in the array. 

NULL The specified wide character does not occur in 
the array. 
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wmemcmp 


Compares two arrays of wide characters. 


Format 

#include <wchar.h> 

int wmemcmp (const wchar_t *s7, const wchar_t “s2, size_t n); 
Arguments 

s1, s2 

Pointers to wide-character arrays. 

n 

The maximum number of wide characters to be compared. 
Description 


The wmemcmp function compares the first n wide characters of the array pointed 
to by sl with the first n wide characters of the array pointed to by s2. The wide 
characters are compared not according to locale-dependent collation rules, but as 
integral objects of type wchar t. 


Return Values 


0 Arrays are equal. 
Positive value The first array is greater than the second. 
Negative value The first array is less than the second. 
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wmemcpy 


Format 


Copies a specified number of wide characters from one wide-character array to 
another. 


#include <wchar.h> 


wchar_t wmemcpy (wchar_t “dest, const wchar_t “source, size_t n); 


Function Variants 


Arguments 


Description 


The wmemcpy function has variants named wmemcpy32 and wmemcpyé4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


dest 
A pointer to the destination array. 


source 
A pointer to the source array. 


n 
The number of wide characters to be copied. 


The wmemcpy function copies n wide characters from the array pointed to by source 
to the array pointed to by dest. 


Return Value 


x The value of dest. 
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wmemmove 


Copies a specified number of wide characters from one wide-character array to 
another. 


Format 
#include <wchar.h> 


wchar_t wmemmove (wchar_t “dest, const wchar_t “source, size_t n); 


Function Variants 


The wmemmove function has variants named wmemmove32 and wmemmoveé4 for 
use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


Arguments 


dest 
A pointer to the destination array. 


source 
A pointer to the source array. 


n 
The number of wide characters to be moved. 
Description 


The wmemmove function copies n wide characters from the location pointed to by 
source to the location pointed to by dest. 


The wmemmove and wmemcpy routines perform the same function, except that 
wmemmove ensures that the original contents of the source array are copied to the 
destination array even if the two arrays overlap. Where such overlap is possible, 
programs that require portability should use wmemmove, not wmemcopy. 


Return Value 


x The value of dest. 
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wmemset 


Format 


Sets a specified value to a specified number of wide characters in an array of wide 
characters. 


#include <wchar.h> 


wchar_t wmemset (wchar_t “s, wchar_t c, size_t n); 


Function Variants 


Arguments 


Description 


The wmemset function has variants named wmemset32 and wmemseté4 for use 
with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more 
information on using pointer-size-specific functions. 


s 
A pointer to the array of wide characters. 


c 
The value to be placed in the first n wide characters of the array. 


n 
The number of wide characters to be set to the specified value c. 


The wmemset function copies the value of c into each of the first n wide characters 
of the array pointed to by s. 


Return Value 


x The value of s. 
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wprintf 


Format 


Arguments 


Description 


Performs formatted output from the standard output (stdout). See Chapter 2 for 
information on format specifiers. 


#include <wchar.h> 


int wprintf (const wchar_t *format, ... ); 


format 

A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


Optional expressions whose resultant types correspond to conversion 
specifications given in the format specification. 


If no conversion specifications are given, the output sources can be omitted. 
Otherwise, the function calls must have exactly as many output sources as there 
are conversion specifications, and the conversion specifications must match the 
types of the output sources. 


Conversion specifications are matched to output sources in left-to-right order. 
Excess output pointers, if any, are ignored. 


The wprintf function is equivalent to the fwprintf function with the stdout 
argument interposed before the worintf arguments. 


Return Values 
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n The number of wide characters written. 


Negative value 


wprintf 


Indicates an error. The function sets errno to 
one of the following: 


e EILSEQ - Invalid character detected. 
e EINVAL - Insufficient arguments. 


e ENOMEM — Not enough memory available 
for conversion. 


e ERANGE - Floating-point calculations 
overflow. 


e EVMSERR - Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This might indicate that 
conversion to a numeric value failed because 
of overflow. 


The function can also set errno to the following 
as a result of errors returned from the I/O 
subsystem: 


e EBADF - The file descriptor is not valid. 
e EIO— I/O error. 


e ENOSPC — No free space on the device 
containing the file. 


e ENXIO — Device does not exist. 
e EPIPE — Broken pipe. 


e ESPIPE — Illegal seek in a file opened for 
append. 


e EVMSERR -— Nontranslatable OpenVMS 
error. vaxcSerrno contains the OpenVMS 
error code. This indicates that an I/O error 
occurred for which there is no equivalent C 
error code. 
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wrapok 


wrapok 


Format 


Arguments 
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In the UNIX system environment, allows the wrapping of a word from the right 
border of the window to the beginning of the next line. This routine is provided 
only for UNIX software compatibility and serves no function in the OpenVMS 
environment. 


#include <curses.h> 
wrapok (WINDOW *win, bool boolf); 


win 
A pointer to the window. 


boolf 

A Boolean TRUE or FALSE value. If boolf is FALSE, scrolling is not allowed. 
This is the default setting. The bool type is defined in the <curses.h> header file 
as follows: 


#define bool int 


write 


write 


Format 


Arguments 


Description 


Writes a specified number of bytes from a buffer to a file. 


#include <unistd.h> 
ssize_t write (int file_desc, void “buffer, size_t nbytes); (SO POSIX-1) 


int write (int file_desc, void *buffer, int nbytes); (Compatability) 


file_desc 
A file descriptor that refers to a file currently opened for writing or updating. 


buffer 
The address of contiguous storage from which the output data is taken. 


nbytes 
The maximum number of bytes involved in the write operation. 


If the write is to an RMS record file and the buffer contains embedded new-line 
characters, more than one record may be written to the file. Even if there are no 
embedded new-line characters, if nbytes is greater than the maximum record size 
for the file, more than one record will be written to the file. The write function 
always generates at least one record. 


If the write is to a mailbox and the third argument, nbytes, specifies a length 
of 0, an end-of-file message is written to the mailbox. This occurs for mailboxes 
created by the application using SYS$CREMBX, but not for mailboxes created to 
implement POSIX pipes. For more information, see Chapter 5. 


Return Values 


x The number of bytes written. 


—1 Indicates errors, including undefined file 
descriptors, illegal buffer addresses, and physical 
I/O errors. 
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writev 


writev 


Format 


Writes to a file. 


#include <uio.h> 
ssize_t writev (int file_desc, const struct iovec *iov, int iovent): 


ssize_t __writev64 (int file_desc, const struct __iovec64 “iov, int iovent); (Alpha, 164) 


Function Variants 


Arguments 


Description 


REF-812 


The writev function has variants named writev32 and _writev64 for use with 
32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information 
on using pointer-size-specific functions. 


file_desc 
A file descriptor that refers to a file currently opened for writing or updating. 


iov 
Array of iovec structures from which the output data is gathered. 


iovent 
The number of buffers specified by the members of the iovu array. 


The writev function is equivalent to write but gathers the output data from 
the iouvcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., 
iov[iovent—1]. The iovent argument is valid if greater than 0 and less than or 
equal to {IOV_MAX}, defined in <limits.h>. 


Each iovec entry specifies the base address and length of an area in memory 
from which data should be written. The writev function writes a complete area 
before proceeding to the next. 


If filedes refers to a regular file and all of the iov_len members in the array 
pointed to by iov are 0, writev returns 0 and has no other effect. 


For other file types, the behavior is unspecified. 


If the sum of the iov_len values is greater than SSIZE_MAX, the operation fails 
and no data is transferred. 


Upon successful completion, writev returns the number of bytes actually written. 
Otherwise, it returns a value of —1, the file pointer remains unchanged, and 
errno is set to indicate an error. 


Return Values 


writev 


The number of bytes written. 


Indicates an error. The file times do not change, 
and the function sets errno to one of the 
following values: 


EBADF -— The file_desc argument is not a 
valid file descriptor open for writing. 


EINTR — The write operation was terminated 
due to the receipt of a signal, and no data 
was transferred. 


EINVAL — The sum of the iov_len values in 
the iov array would overflow an ssize t, or 
the iovcnt argument was less than or equal 

to 0, or greater than {IOV_MAX}. 


EIO — A physical I/O error has occurred. 


ENOSPC — There was no free space 
remaining on the device containing the 
file. 


EPIPE — An attempt is made to write to a 
pipe or FIFO that is not open for reading by 
any process, or that only has one end open. 
A SIGPIPE signal will also be sent to the 
thread. 
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wscanf 


wscanf 


Format 


Arguments 


Description 


Reads input from the standard input (stdin) under control of the wide-character 
format string. 


#include <wchar.h> 


int wscanf (const wchar_t *format, ... ); 


format 

A pointer to a wide-character string containing the format specifications. 
For more information about format and conversion specifications and their 
corresponding arguments, see Chapter 2. 


Optional expressions whose results correspond to conversion specifications given 
in the format specification. 


If no conversion specifications are given, you can omit the input pointers. 
Otherwise, the function calls must have exactly as many input pointers as there 
are conversion specifications, and the conversion specifications must match the 
types of the input pointers. 


Conversion specifications are matched to input sources in left-to-right order. 
Excess input pointers, if any, are ignored. 


The wscanf function is equivalent to the fwscanf function with the stdin 
arguments interposed before the wscanf arguments. 


Return Values 
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n The number of input items assigned. The 
number can be less than provided for, even 
zero, in the event of an early matching failure. 


EOF Indicates an error. An input failure occurred 
before any conversion. 


yO, y1, yn aipna, 164) 


yO, y1, YN Apna, 164 


Format 


Arguments 


Description 


Compute Bessel functions of the second kind. 


#include <math.h> 

double yO (double x); 

float yOf (float x); 

long double yOl (long double x); 
double y1 (double x); 

float y1f (float x); 

long double y1! (long double x); 
double yn (int n, double x); 
float ynf (int n, float x); 


long double yn! (int n, long double x); 


Xx 
A positive, real value. 


n 
An integer. 


The yO functions return the value of the Bessel function of the second kind of 


order 0. 


The y1 functions return the value of the Bessel function of the second kind of 


order 1. 


The yn functions return the value of the Bessel function of the second kind of 


order n. 


Return Values 


x The relevant Bessel value of x of the second kind. 

—HUGE_VAL The x argument is 0.0; errno is set to ERANGE. 

NaN The x argument is negative or NaN; errno is set 
to EDOM. 

0 Underflow occurred; errno is set to ERANGE. 

HUGE_VAL Overflow occurred; errno is set to ERANGE. 
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A 


Version-Dependency Tables 


New functions are added to the HP C Run-Time Library with each version 
of HP C. These functions are implemented and shipped with the OpenVMS 
operating system, while the documentation and header files containing their 


prototypes are shipped with versions of the HP C compiler. 


You might have a newer version of HP C that has header files and documentation 
for functions that are not supported on your older OpenVMS system. For 
example, if your target operating system platform is OpenVMS Version 7.2, 

you cannot use HP C RTL functions introduced on OpenVMS Version 7.3, even 
though they are documented in this manual. 


This appendix contains several tables that list what HP C RTL functions are 
supported on recent OpenVMS versions. This is helpful for determining the 
functions to avoid using on your target OpenVMS platforms. 


A.1 Functions Available on all OpenVMS VAX, Alpha, and 164 
Versions 


Table A—1 lists functions available on all OpenVMS VAX and OpenVMS Alpha 
versions. 


Table A-1 Functions Available on All OpenVMS Systems 


abort abs access acos 

alarm asctime asin assert 

atan2 atan atexit atof 

atoi atoll (Alpha) atol atoq (Alpha) 
box brk bsearch cabs 

calloc ceil cfree chdir 

chmod chown clearerr clock 

close cosh cos creat 

ctermid ctime cuserid decc$crtl_init 


decc$fix_time 


decc$record_write 


decc$from_vms 


decc$set_reentrancy 


decc$match_wild 


decc$to_vms 


decc$record_read 


decc$translate_vms 


delete delwin difftime div 
dup2 dup ecvt endwin 
execle execlp execl execve 
execvp execv exit _exit 
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Table A-1 (Cont.) Functions Available on All OpenVMS Systems 


exp 
fdopen 

fgetc 

fileno 
fprintf 

free 

fseek 

ftell 

gevt 

getegid 
getname 
getuid 
hypot 
isapipe 
isdigit 
ispunct 

kill 

llabs (Alpha) 
log10 

lseek 
mbstowcs 
memcpy 
mktemp 
mv[wladdstr 
overlay 

pipe 

putc 

qdiv (Alpha) 
read 

rewind 
setbuf 
setuid 
sigpause 

sin 

srand 

strceat 

strcpy 
strlen 
strpbrk 


A-2 Version-Dependency Tables 


fabs 

feof 
fgetname 
floor 
fputc 
freopen 
fsetpos 
ftime 
getchar 
getenv 
getpid 
getw 
initscr 
isascil 
isgraph 
isspace 
labs 

lldiv (Alpha) 
log 

lwait 
mbtowc 
memmove 
mktime 
newwin 
overwrite 
pow 

puts 
qsort 
realloc 
sbrk 
setgid 
setvbuf 
sigstack (VAX) 
sleep 
sscanf 
strchr 
strespn 
strncat 


strrchr 


fclose 
ferror 
fgetpos 
fmod 
fputs 
frexp 
fstat 
fwait 
getcwd 
geteuid 
getppid 
gmtime 
isalnum 
isatty 
islower 
isupper 
Idexp 
localeconv 
longjmp 
malloc 
memchr 
memset 
modf 
nice 
pause 
printf 
putw 
raise 
remove 
scanf 
setjmp 
sigblock 
sigvec 
sprintf 
ssignal 
strcmp 
strerror 
strncmp 


strspn 


fevt 
fflush 
fgets 
fopen 
fread 
fscanf 
fsync 
fwrite 
getc 
getgid 
gets 
gsignal 
isalpha 
iscntrl 
isprint 
isxdigit 
ldiv 
localtime 
longname 
mblen 
memcmp 
mkdir 
mvwin 
open 
perror 
putchar 
qabs (Alpha) 
rand 
rename 
scroll 
setlocale 
signal 
sinh 

sqrt 

stat 
strcoll 
strftime 
strncpy 


strstr 
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strtod 

strtoq (Alpha) 
strxfrm 

tan 

tmpnam 
touchwin 
umask 
vaxc$ertl_init 
vaxc$realloc_opt 
va_start 
vprintf 
wcetomb 
[w]clear 
[w]delch 
[wlgetstr 
[wlinsstr 


[w]scanw 


strtok 

strtoull (Alpha) 
subwin 

times 

toascli 

toupper 
ungetc 
vaxc$establish 
va_arg 
va_start_1 
vsprintf 

write 
[wlelrattr 
[wldeleteln 
[wlinch 
[w]move 


[w]setattr 


strtoll (Alpha) 
strtoul 

system 

time 

tolower 
_toupper 
vaxc$calloc_opt 
vaxc$free_opt 
va_count 
vfork 

wait 

[wladdch 
[wlelrtobot 
[wlerase 
[wlinsch 
[w]printw 


[w]standend 


strtol 

strtouq (Alpha) 
tanh 

tmpfile 
_tolower 
ttyname 
vaxc$cfree_opt 
vaxc$malloc_opt 
va_end 
vfprintf 
westombs 
[wladdstr 
[wlclrtoeol 
[wlgetch 
[wlinsertln 
[wlrefresh 


[w]standout 


A.2 Functions Available on OpenVMS Version 6.2 and Higher 


Table A—2 lists functions available on OpenVMS VAX and OpenVMS Alpha 
Version 6.2 and higher. 


Table A-2 Functions Added in OpenVMS Version 6.2 


catclose 
fgetws 
getwc 
iconv_open 
iswctype 
iswprint 
iswxdigit 
strnlen 
ungetwc 
wescoll 
weslen 
wespbrk 
westoul 


westod 


catgets 
fputwe 
getwchar 
iswalnum 
iswdigit 
iswpunct 
nl_langinfo 
strptime 
wescat 
wescpy 
wesncat 
wesrchr 
WcsSwcs 


wctype 


catopen 
fputws 
iconv 
iswalpha 
iswgraph 
iswspace 
putwe 
towlower 
weschr 
wesespn 
wesncmp 
wesspn 
weswidth 
wewidth 


fgetwe 
getopt 
iconv_close 
iswentrl 
iswlower 
iswupper 
putwchar 
towupper 
wescmp 
wesftime 
wesncpy 
westol 
wesxfrm 


westok 


Version-Dependency Tables A-3 


A.3 Functions Available on OpenVMS Version 7.0 and Higher 


Table A—3 lists functions available on OpenVMS VAX and OpenVMS Alpha 
Version 7.0 and higher. 


Table A-3 Functions Added in OpenVMS Version 7.0 


basename 
bzero 
drand48 
ftruncate 
fwscanf 
getlogin 
gettimeofday 
Icong48 
mbsinit 
mmap 
munmap 
pclose 
readdir 
seed48 
setstate 
sigemptyset 
sigpending 
srand48 
strfmon 
swprintf 
tempnam 
ualarm 
usleep 
wait3 
wesrtombs 
wmemchr 


wmemset 


bemp 
closedir 
erand48 
ftw 
getclock 
getpagesize 
index 
lrand48 
mbsrtowcs 
mprotect 
nrand48 
popen 
rewinddir 
seekdir 
sigaction 
sigfillset 
sigprocmask 
srandom 
strncasecmp 
swscanf 
towctrans 
uname 
vfwprintf 
wait4 
wesstr 
wmemcmp 


wprintf 


bcopy 
confstr 

ffs 

fwide 
getdtablesize 
getpwnam 
initstate 
mbrlen 
memccpy 
mrand48 
opendir 
putenv 
rindex 
setenv 
sigaddset 
sigismember 
sigsetjmp 
strcasecmp 
strsep 
sysconf 
truncate 
unlink 
vswprintf 
waitpid 
wctob 
wmemcpy 


wscanf 


btowc 
dirname 
fpathconf 
fwprintf 
getitimer 
getpwuid 
jrand48 
mbrtowc 
mkstemp 
msync 
pathconf 
random 
rmdir 
setitimer 
sigdelset 
siglongjmp 
sigsuspend 
strdup 
swab 
telldir 
tzset 
unsetenv 
vwprintf 
wertomb 
wetrans 


wmemmove 
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A.4 Functions Available on OpenVMS Alpha Version 7.0 and Higher 
Table A—4 lists functions available on OpenVMS Alpha Version 7.0 and higher. 


Table A-4 Functions Added in OpenVMS Alpha Version 7.0 


_basename32 _basename64 _bsearch32 _bsearch64 
_calloc32 _calloc64 _catgets32 _catgets64 
_ctermid32 _ctermid64 _cuserid32 _cuserid64 
_dirname32 _dirname64 _fgetname32 _fgetname64 
_fgets32 _fgets64 _fgetws32 _fgetws64 
_gevt32 _gevt64 _getcwd32 _getcwd64 
_getname32 _getname64 _gets32 _gets64 
_index32 _index64 _longname32 _longname64 
_malloc32 _malloc64 _mbsrtowcs32 _mbsrtowcs64 
_memccpy32 _memccpy64 _memchr32 _memchr64 
_memcpy32 _memcpy64 _memmove32 _memmove64 
_memset32 _memset64 _mktemp32 _mktemp64 
_mmap32 _mmap64 _qsort32 _qsort64 
_realloc32 _realloc64 _rindex32 _rindex64 
_strcat32 _streat64 _strchr32 _strchr64 
_strepy32 _strepy64 _strdup32 _strdup64 
_strncat32 _strncat64 _strnepy32 _strncpy64 
_strpbrk32 _strpbrk64 _strptime32 _strptime64 
_strrehr32 _strrchr64 _strsep32 _strsep64 
_strstr32 _strstr64 _strtod32 _strtod64 
_strtok32 _strtok64 _strtol32 _strtol64 
_strtoll32 _strtoll64 _strtoq32 _strtoq64 
_strtoul32 _strtoul64 _strtoull32 _strtoull64 
_strtoug32 _strtouq64 _tmpnam32 _tmpnam64 
_wescat32 _wescat64 _weschr32 _weschr64 
_wescpy32 _wescpy64 _wesncat32 _wesncat64 
_wesncpy32 _wesncpy64 _wespbrk32 _wespbrk64 
_wesrchr32 _wesrchr64 _wesrtombs32 _wesrtombs64 
_wesstr32 _wesstr64 _westok32 _westok64 
_westol32 _westol64 _westoul32 _westoul64 
_weswes32 _weswes64 _wmemchr32 _wmemchr64 
_wmemcpy32 _wmemcpy64 _wmemmove32 _wmemmove64 
_wmemset32 _wmemset64 
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A.5 Functions Available on OpenVMS Version 7.2 and Higher 


Table A—5 lists functions available on OpenVMS VAX and OpenVMS Alpha 
Version 7.2 and higher. 


Table A-5 Functions Added in OpenVMS Version 7.2 


asctime_r dlerror 
ctime_r dlopen 
decc$set_child_standard_streams disym 
decc$validate_wchar fentl 
decc$write_eof_to_mbx emtime_r 
dlclose localtime_r 


A.6 Functions Available on OpenVMS Version 7.3 and Higher 


Table A-6 lists functions available on OpenVMS VAX and OpenVMS Alpha 
Version 7.3 and higher. 


Table A-6 Functions Added in OpenVMS Version 7.3 


fechown 
link 
utime 
utimes 


writev 


A.7 Functions Available on OpenVMS Version 7.3-1 and Higher 
Table A-7 lists functions available on OpenVMS Alpha Version 7.3-1 and higher. 


Table A-7 Functions Added in OpenVMS Version 7.3-1 


access ftello 
chmod ftw 
chown readdir_r 
decc$feature_get_index stat 
decc$feature_get_name vfscanf 
decc$feature_get_value vfwscanf 
decc$feature_set_value vscanf 
fseeko vwscanf 
fstat vsscanf 
vswscanf 
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A.8 Functions Available on OpenVMS Version 7.3-2 and Higher 
Table A-8 lists functions available on OpenVMS Alpha Version 7.3-2 and higher. 


Table A-8 Functions Added in OpenVMS Version 7.3-2 


a64l clock_getres clock_gettime clock_settime 
endgrent getgrent getgrgid getgrgid_r 
getgrnam getgrnam_r getpgid getperp 
_getpwnam64 getpwnam_r _getpwnam_r64 _getpwent64 
getpwuid _getpwuid64 getpwuid_r _getpwuid_r64 
getsid 164a nanosleep poll 

pread pwrite rand_r readv 
_readv64 seteuid setgrent setpgid 
setpgrp setregid setreuid setsid 

sighold sigignore sigrelse sigtimedwait 
sigwait sigwaitinfo snprintf ttyname_r 
vsnprintf __writev64 decc$set_child_ 


default_dir 


A.9 Functions Available on OpenVMS Version 8.2 and Higher 


Table A-9 lists functions available on OpenVMS Alpha and 164 Version 8.2 and 
higher. 


Table A-9 Functions Added in OpenVMS Version 8.2 


clearerr_unlocked feof_unlocked 
ferror_unlocked fgetc_unlocked 
fputc_unlocked flockfile 
ftrylockfile funlockfile 
getc_unlocked getchar_unlocked 
putc_unlocked putchar_unlocked 
statvfs fstatvfs 

_glob32 _glob64 
_globfree32 _globfree64 
socketpair 


A.10 Functions Available on OpenVMS Version 8.3 and Higher 


Table A-10 lists functions available on OpenVMS Alpha and 164 Version 8.3 and 
higher. 
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Table A-10 Functions Added in OpenVMS Version 8.3 


crypt readlink 
encrypt realpath 
setkey symlink 
Ichown unlink 
Istat fchmod 


A-8 Version-Dependency Tables 


Prototypes Duplicated to Nonstandard Headers 


The various standards dictate which header file must define each of the standard 
functions. This is the included header file documented with each function 
prototype in the Reference Section of this manual. 


However, many of the functions defined by the standards already existed on 
several operating systems and were defined in different header files. This is 
especially true on OpenVMS systems with the header files <processes.h>, 
<unixio.h>, and <unixlib.h>. 


So, to provide upward compatibility for these functions, their prototypes are 
duplicated in both the expected header file as well as the header file defined by 
the standards. 


Table B—1 lists these functions. 


Table B—1 Duplicated Prototypes 


Function Duplicated in Standard says 
access <unixio.h> <unistd.h> 
alarm <signal.h> <unistd.h> 
bemp <string.h> <strings.h> 
bcopy <string.h> <strings.h> 
bzero <string.h> <strings.h> 
chdir <unixio.h> <unistd.h> 
chmod <unixio.h> <stat.h> 
chown <unixio.h> <unistd.h> 
close <unixio.h> <unistd.h> 
creat <unixio.h> <fentl.h> 
ctermid <stdio.h> <unistd.h> 
cuserid <stdio.h> <unistd.h> 
dirname <string.h> <libgen.h> 
dup <unixio.h> <unistd.h> 
dup2 <unixio.h> <unistd.h> 
ecvt <unixlib.h> <stdlib.h> 
execl <processes.h> <unistd.h> 
execle <processes.h> <unistd.h> 
execlp <processes.h> <unistd.h> 
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Table B-1 (Cont.) Duplicated Prototypes 


Function Duplicated in Standard says 
execv <processes.h> <unistd.h> 
execve <processes.h> <unistd.h> 
execvp <processes.h> <unistd.h> 
_exit <stdlib.h> <unistd.h> 
fevt <unixlib.h> <stdlib.h> 
ffs <string.h> <strings.h> 
fsyne <stdio.h> <unistd.h> 
ftime <time.h> <timeb.h> 
gevt <unixlib.h> <stdlib.h> 
getcwd <unixlib.h> <unistd.h> 
getegid <unixlib.h> <unistd.h> 
getenv <unixlib.h> <stdlib.h> 
geteuid <unixlib.h> <unistd.h> 
getgid <unixlib.h> <unistd.h> 
getopt <stdio.h> <unistd.h> 
getpid <unixlib.h> <unistd.h> 
getppid <unixlib.h> <unistd.h> 
getuid <unixlib.h> <unistd.h> 
index <string.h> <strings.h> 
isatty <unixio.h> <unistd.h> 
lseek <unixio.h> <unistd.h> 
mkdir <unixlib.h> <stat.h> 
mktemp <unixio.h> <stdlib.h> 
nice <stdlib.h> <unistd.h> 
open <unixio.h> <fentl.h> 
pause <signal.h> <unistd.h> 
pipe <processes.h> <unistd.h> 
read <unixio.h> <unistd.h> 
rindex <string.h> <strings.h> 
sbrk <stdlib.h> <unistd.h> 
setgid <unixlib.h> <unistd.h> 
setuid <unixlib.h> <unistd.h> 
sleep <signal.h> <unistd.h> 
strcasecmp <string.h> <strings.h> 
strncasecmp <string.h> <strings.h> 
system <processes.h> <stdlib.h> 
times <time.h> <times.h> 
umask <stdlib.h> <stat.h> 


B-2 Prototypes Duplicated to Nonstandard Headers 
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Table B-1 (Cont.) Duplicated Prototypes 


Function Duplicated in Standard says 
vfork <processes.h> <unistd.h> 
wait <processes.h> <wait.h> 

write <unixio.h> <unistd.h> 


Prototypes Duplicated to Nonstandard Headers B-3 


64-bit pointer support, 1-58 
32-bit UIDs, GIDs, 1-44 
2-gigabyte files, 1-26 


A 


a641 function, REF-3 
abort function, 4-1, REF-5 
abs function, REF-6 
access function, REF-—7 
ACCVIO 
hardware error, 1-54 
sigbus signal, 4-10 
sigsegv signal, 4-11 
acos function, REF—9 
acosh function, REF-10 
addch function, REF-—11 
addstr function, REF-12 
alarm function, 4—1, 4-10, REF-13 
program example, 4-14 
Allocate memory 
calloc function, REF-38 
malloc function, REF-387 
realloc function, REF-498 
_ANSI_C_SOURCE macro, 1-19 
Argument list functions, 3-9 to 3-12 
Arguments 
variable-length lists, 3-9 
ASCII 
table of values, 3-4 
asctime function, REF-14 
asctime_r function, REF-14 
asin function, REF-16 
asinh function, REF-17 
asm calls, 1-54 
assert function, REF-18 
AST reentrancy, 1-55, REF—-124 
atan function, REF-19 
atan2 function, REF-—20 
atanh function, REF-21 
atexit function, REF-22 
atof function, REF-23 
atoi function, REF-24 
atol function, REF—24 
atoll function, REF—25 


Index 


atog function, REF—25 


basename function, REF-—26 
bemp function, REF—27 

bcopy function, REF—28 

box function, REF—29 

brk function, 8-1, REF—30 
_BSD44_CURSES macro, 1-25 
bsearch function, REF-31 
btowc function, 10-10, REF-33 
bzero function, REF-34 


Cc 


C language 

V/O background, 1-45 
C RTL 

See Run-Time Library (RTL) 

new features, xxix 

POSIX Root, 1-32 
C$_LONGJMP exception, 4—11 
cabs function, REF—35 
cacos function, REF-36 
cacosh function, REF-37 
calloc function, 8—1, REF-38, REF—56 
carg function, REF-39 
Carriage control 

Fortran, 1-49 

translation 

by HPC, 1-48 to 1-50 

Case conversion functions, 10-9 
casin function, REF—40 
casinh function, REF-—41 
catan function, REF—42 
catanh function, REF—43 
catclose function, 10-5, REF—44 


Categories 
locale, 10-3 
Category 
LC_ALL, 10-4 


LC_COLLATE, 10-3 
LC_CTYPE, 10-3 
LC_MESSAGES, 10-3 
LC_MONETARY, 10-3 
LC_NUMERIC, 10-3 
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Category (cont'd) Character-conversion functions (cont’d) 


LC_TIME, 10-3 towupper, REF-689 

catgets function, 10-5, REF—45 wceswidth, REF—792 

catopen function, 10-5, REF—48 wewidth, REF-802 

cbrt function, REF-51 Charmap file 

ccos function, REF—52 location, 10-6 

ccosh function, REF-53 chdir function, REF-57 

ceil function, REF-54 Child process 

cexp function, REF-55 creating with vfork, REF-—721 

cfree function, 8-1, REF—56 executing image 

Character definition files with exec functions, 5-3 
location of, 10-6 implementation of, 5-2 

Character set conversion functions introduction to, 5-1 
iconv, REF-314 program examples, 5-5 
iconv_close, REF-316 sharing data with pipe, 5-5, REF—459 
iconv_open, REF-317 synchronization with wait, 5-5 

Character sets chmod function, REF-58 
converting between, 10-6 chown function, REF—-59 
supported by HP C RTL, 10-6 cimag function, REF-—60 

Character special files, 12-3 clear function, REF-61, REF-64 

Character-classification functions, 3—4 to 3-7, learerr function, REF-—62 


10-9 

isalnum, REF-328 
isalpha, REF-329 
isascii, REF-331 
iscntrl, REF-333 


ic 
clearerr unlocked function, REF-63 
Cc 
c 
c 
C 
isdigit, REF-334 C 
ic 
c 
Cc 
c 
c 
ic 


earok function, REF-64 

ock function, REF-65 
ock_getres function, REF-66 
ock_gettime function, REF-67 
ock_settime function, REF—68 
og function, REF—70 

ose function, REF-71 

osedir function, REF—72 
rattr function, REF-74 

rattr macro, 6—2 

rtobot function, REF—75 


isgraph, REF-335 
islower, REF-336 
isprint, REF-338 
ispunct, REF-339 
isspace, REF-340 
isupper, REF-341 


iswalnum, REF-342 clrtoeol function, REF—76 

iswalpha, REF-343 Codeset converter functions, 10-6 

iswentrl, REF-344 Codesets, 10-6 

iswctype, REF-345 confstr function, REF-77 

iswdigit, REF-347 conj function, REF—79 

iswgraph, REF-348 Conversion specifications 

iswlower, REF-349 for I/O functions, 2-7 to 2-19 

iswprint, REF-350 input 

iswpunct, REF-351 table of conversion specifiers, 2-8 

iswspace, REF-352 table of optional characters, 2-8 

iswupper, REF-353 output 

iswxdigit, REF-354 table of characters, 2-16 

isxdigit, REF-355 Converter functions 

program example, 3-7 filenaming conventions for, 10-6 

wctype, REF-799 copysign function, REF-80 
Character-conversion functions, 3—7 to 3-9 cos function, REF—-81 

ecvt, REF-149 cosh function, REF—82 

fevt, REF-179 cot function, REF-83 

gcvt, REF-252 cpow function, REF-84 

toascii, REF-681 cproj function, REF-—85 

tolower, REF-682 creal function, REF-86 

_tolower, REF-683 creat function, REF—87, REF—-147, REF-173, 

toupper, REF-685 REF-182 


_toupper, REF-686 
towlower, REF-688 
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crmode function, REF-—93 
crypt function, REF-94 
csin function, REF—95 
csinh function, REF-96 
csqrt function, REF-97 
ctan function, REF—-98 
ctanh function, REF-99 
ctermid function, REF—100 
ctime function, REF-14, REF-101 
using with tzset function, REF—694 
ctime_r function, REF-101 
Cultural information 
stored in locale, 10-8 
curscr window, 6—5 
Curses, 6-1 to 6-13 
cursor movement, 6-10 
getting started, 6—7 to 6-9 
introduction to, 6-1 
program example, 6-11 
terminology, 6—4 to 6-7 
curscr, 6-5 
stdscr, 6-5 
windows, 6—5 
using predefined variables and constants, 6-9 
Curses functions 
box, REF-29 
clearok, REF-64 
delwin, REF-137 
endwin, REF-154 
getyx, REF-303 
initscr, REF-322 
leaveok, REF-365 
longname, REF-379 
mvcur, REF-—426 
mvwin, REF-433 
mv [w]addch, REF-424 
mv[w]addstr, REF—425 
mv [w]delch, REF—427 
mv[w]getch, REF—428 
mv[w]getstr, REF—429 
mv[w] inch, REF-430 
mv[w]insch, REF-431 
mv[w]insstr, REF—432 
newwin, REF—436 
[no] crmode, REF—-93 
[no]echo, REF-148 
[no]nl, REF—441 
[no] raw, REF—489 
overlay, REF-452 
overwrite, REF—453 
scroll, REF-516 
scrollok, REF-517 
subwin, REF—656 
touchwin, REF-684 
wrapok, REF-810 
[w]addch, REF-11 
[wladdstr, REF-12 
[w] clear, REF-61 


Curses functions (cont’d) 
[w]clrattr, REF—74 
]clrtobot, REF—75 
]clrtoeol, REF—-76 
]delch, REF-134 
]deleteln, REF-136 
Jerase, REF-156 
getch, REF—256 
]getstr, REF-297 
inch, REF-320 
Jinsch, REF-325 
insertln, REF-326 
Jinsstr, REF-327 
]move, REF-417 
]printw, REF-471 
refresh, REF-501 
]scanw, REF-515 
]setattr, REF—-520 
]standend, REF—593 
[w] standout, REF—594 
<curses.h> header file, 6-2 
cuserid function, REF—103 
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Date and time functions, 10-8 
Date/time 
introduction to, 11-1 
Date/time functions, 11-1 to 11-6 
DCL 
symbolic link support, 12-15 

DECC$ACL_ACCESS_CHECK feature logical, 
1-31 

DECC$ALLOW_REMOVE_OPEN_FILES feature 
logical, 1-31 

DECC$ALLOW_UNPRIVILEGED_NICE feature 
logical, 1-31, REF—439 

DECC$ARGV_PARSE_STYLE feature logical, 
1-31 

DECCSCRTL_ INIT function, REF—-104, REF—699 

DECC$DEFAULT_LRL feature logical, 1-32 

DECC$DEFAULT_UDF_RECORD feature logical, 
1-382 

DECC$DETACHED_CHILD_PROCESS feature 
logical, 1-32 

DECC$DISABLE_POSIX_ROOT feature logical, 
1-382 

DECC$DISABLE_TO_VMS_LOGNAME_ 
TRANSLATION feature logical, 1-33 

DECC$EFS_CASE_PRESERVE feature logical, 
1-33 

DECC$EFS_CASE_SPECIAL feature logical, 
1-33 

DECC$EFS_CHARSET feature logical, 1-33 

DECC$EFS_FILE_TIMESTAMPS feature logical, 
1-34 
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DECC$EFS_NO_DOTS_IN_DIRNAME feature 
logical, 1-34 

DECC$ENABLE_GETENV_CACHE feature 
logical, 1-34 

DECC$ENABLE_TO_VMS_LOGNAME_CACHE 
feature logical, 1-35 

DECC$EXEC_FILEATTR_INHERITANCE feature 
logical, 1-35 

deccSfeature get feature-setting routine, 
REF-105 

deccSfeature get index feature-setting 
routine, REF—-106 

decc$feature_get_name feature-setting routine, 
REF-107 

deccSfeature get value feature-setting 
routine, REF-108 

deccSfeature set feature-setting routine, 
REF-109 

deccS$feature_set_value feature-setting 
routine, REF—-110 

deccSfeature_show feature-setting routine, 
REF-111 

deccSfeature show all feature-setting routine, 
REF-112 

DECC$FILENAME_UNIX_NO_VERSION feature 
logical, 1-35 

DECC$FILENAME_UNIX_ONLY feature logical, 
1-35 

DECC$FILENAME_UNIX_REPORT feature 
logical, 1-36 

DECC$FILE_PERMISSION_UNIX feature logical, 
1-36 

DECC$FILE_SHARING feature logical, 1-36 

DECC$FIXED_LENGTH_SEEK_TO_EOF feature 
logical, 1-36 

decc$fix_time file specification conversion 
routine, 1-16, REF-113 

decc$from_vms file specification conversion 
routine, 1-16, REF-114 

DECC$GLOB_UNIX_STYLE feature logical, 1-36 

DECC$LOCALE_CACHE_SIZE feature logical, 
1-36 

DECC$MAILBOX_CTX_STM feature logical, 1-36 

deccSmatch_ wild file specification conversion 
routine, 1-16, REF-116 

DECC$NO_ROOTED_SEARCH_LISTS feature 
logical, 1-36 

DECC$PIPE_BUFFER_QUOTA feature logical, 
1-87, REF—460 

DECC$PIPE_BUFFER_SIZE feature logical, 
1-38, REF—460 

DECC$POPEN_NO_CRLF_REC_ATTR feature 
logical, 1-388, REF—462 

DECC$POSIX_COMPLIANT_PATHNAMES 
feature logical, 1-38, 12-1, 12-8 
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DECC$POSIX_SEEK_STREAM_FILE feature 
logical, 1-39 

DECC$POSIX_STYLE_UID feature logical, 1-39 

DECC$READDIR_DROPDOTNOTYPE feature 
logical, 1-39 

DECC$READDIR_KEEPDOTDIR feature logical, 
1-39 

deccSrecord read function, REF-117 

deccSrecord write function, REF—118 

DECC$RENAME_ALLOW_DIR feature logical, 
1-40 

DECC$RENAME_NO_INHERIT feature logical, 
1-39 

DECC$SELECT_IGNORES_INVALID_FD feature 
logical, 1-40 

deccSset child default dir function, 
REF-119 

decc$set_ child standard_streams function, 
REF-120 

decc$set_reentrancy function, 1-56, REF—124 

DECC$SHR.EXE, 1-3 

DECC$STDIO_CTX_EOL feature logical, 1-41 

DECC$STREAM_PIPE feature logical, 1-41, 
REF-462 

DECC$STRTOL_ERANGE feature logical, 1-41 

DECC$THREAD_DATA_AST_SAFE feature 
logical, 1-41 

deccS$to_vms file specification conversion routine, 
1-16, REF—126 

deccStranslate_vms file specification conversion 
routine, 1-16, REF—128 

DECC$TZ_CACHE_SIZE feature logical, 1-41 

DECC$UMASK feature logical, 1-41 

DECC$UNIX_LEVEL feature logical, 1-41 

DECC$UNIX_PATH_BEFORE_LOGNAME feature 
logical, 1-48 

DECC$USE_JPI$_CREATOR feature logical, 
1-43 

DECC$USE_RAB64 feature logical, 1-43 

DECC$V62_RECORD_GENERATION feature 
logical, 1-48 

DECC$VALIDATE_SIGNAL_IN_KILL feature 
logical, 1-48 

deccS$validate wchar function, REF-130 

deccSwrite eof to mbx function, REF-131 

DECC$WRITE_SHORT_RECORDS feature logical, 
1-43 

DECC$XPG4_STRPTIME feature logical, 1-44 

DECC_SHORT_GID_T macro, 1-26 
_DECC_V4_SOURCE macro, 1-24 
DEC/SHELL 
See UNIX file specifications 

delch function, REF—134 

delete function, REF—135, REF—504 

deleteln function, REF-—136 


delwin function, REF—137 

difftime function, REF-138 

dirname function, REF-139 

div function, REF-141 

dlcose function, REF—142 

dlerror function, REF-143 

dlopen function, REF-144 

dlsym function, REF-145 

drand48 function, REF-146 
using with 1cong48 function, REF-362 
using with seed48 function, REF—518 
using with srand48 function, REF—588 

dup function, REF—147, REF—182 


dup2 function, REF—-147, REF—182, REF—461 


E 


echo function, REF—-148 
ecvt function, 3-7, REF—-149 
edata global symbol, 1-54 
EFS, 1-18 
encrypt function, REF-151 
end global symbol, 1-54 
endgrent function, REF—152 
endpwent function, REF-153 
endwin function, REF-154 
erand48 function, REF-155 
erase function, REF—156 
erf function, REF—157 
ERR predefined macro, 6-10 
errno variable, 4—2, 4-5, 7-4 
<errno.h> header file, 4—2, 4-5 
<errnodef.h> header file, 4-11 
Error-handling functions, 4—2 
abort, 4-1, 4-6, 4-10, REF-5 
error codes, 4-2 
exit, 4-1, 5-5, REF-165 
_exit, 4-1, 5-5, REF—-165 
perror, 4-1, REF-458 
strerror, 4-1, REF-612 
etext global symbol, 1-54 
exec function, REF—460 
exec functions 
processing, 5-4 
exec functions, 5-3 
error conditions, 5-5 
execl function, REF-—158 
execle function, REF—160 
execlp function, REF-161 
execv function, REF—162 
execve function, REF-163 
execvp function, REF—164 
_exit function, 5-5 
exit function, 5-5, REF-165 
_exit function, REF-—165 
exit, exit function 
using with wait3 function, REF—741 
using with wait4 function, REF—744 


exit, exit function (cont’d) 
using with waitpid function, REF—747 
exp function, REF-167 
exp2 function, REF-168 
Extended File Specifications, 1-18 
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fabs function, REF-169 

_FAST_TOUPPER, 1-27 

fchmod function, REF—170 

fchown function, REF-171 

fclose function, REF-172, REF—208 

fentl function, REF-173 

fcvt function, 38-7, REF—-179 

fdim function, REF-181 

fdopen function, REF—182, REF—461 

Feature logical names, 1-28 

Feature switches, 1-28 

Feature-setting routines 
deccSfeature get, REF-105 
deccSfeature get index, REF-106 
deccSfeature get name, REF-107 
deccSfeature get value, REF-108 
deccSfeature set, REF-109 
deccSfeature set value, REF-110 
decc$feature_ show, REF-111 
decc$feature_show all, REF-112 

Feature-test macros, 1-18 

feof function, REF-183 

feof unlocked function, REF-184 

ferror function, REF—185 

ferror_ unlocked function, REF-186 

fflush function, REF—187 
using with popen function, REF—466 

ffs function, REF-188 

fgetc function, REF-189 

fgetc_unlocked function, REF-190 

fgetname function, REF-191 

fgetpos function, REF—192 

fgets function, REF—194 

fgetwc function, REF-196 

fgetws function, REF—-197 

File 
header, 1-1 

FILE, 2-5 

File descriptor, 2-5, 2-20 
HP C defaults 

for OpenVMS logical names, 1-18 

File pointer, 2-5, 2-20 

File protection, REF—58, REF-699 

File specification conversion routines 
deccSfix time, REF-113 
deccSfrom_vms, REF-114 
deccSmatch wild, REF-116 
deccSto vms, REF-126 
decc$translate_vms, REF-128 
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fileno function, REF-199 
finite function, REF—200 
Fixed-length record files 
accessing in record mode, 1-51 
Floating-point support, 1-4 
flockfile function, REF-201 
floor function, REF—202 
fma function, REF-203 
fmax function, REF-204 
fmin function, REF-205 
fmod function, REF—206 
fopen function, REF-207 
fork function, REF—721 
Format 
specification string for input functions, 2-7 
specification string for output functions, 2-13 
fpathconf function, REF—210 
fprintf function, REF—212 
fputc function, REF-214 
fputc_unlocked function, REF-215 
fputs function, REF—216 
fputwe function, REF-217 
fputws function, REF-219 
fp_class function, REF-209 
fp_classf function, REF—209 
fp _classl function, REF-209 
fread function, REF—220 
free function, 8-1, REF—56, REF—221, REF-260 
using with tempnam function, REF-675 
freopen function, REF—222 
frexp function, REF-—223 
fscanf function, REF—225 
fseek function, 1-47, REF-227, REF-701, 
REF-702 
fseeko function, REF-229 
fsetpos function, REF—230 
fstat function, REF-231 
fstatvfs function, REF-234 
fsync function, REF-—236 
ftell function, REF—237 
ftello function, REF—238 
ftime function, REF—239 
ftruncate function, REF—240 
ftrylockfile function, REF-241 
ftw function, REF-242 
Function prototype, 1-14 
Functions 
argument list-handling, 3-9 
case conversion, 10-9 
character classification, 10-9 
character-classification, 3—4 
character-conversion, 3—7, 3-8 
Curses, 6-1 to 6-4 
Date/time, 11-1 to 11-6 
error-handling, 4—2 to 4-5 
signal-handling, 4-5 to 4-14 
Standard I/O, 2-1, 2-5 
string-handling, 3-9 
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Functions (cont’d) 

Terminal I/O, 2-19 

Time, 11-1 to 11-6 

UNIX I/O, 2-5 
funlockfile function, REF-244 
fwait function, REF—245 
fwide function, REF—246 
fwprintf function, REF—247 
fwrite function, REF-249 
fwscanf function, REF—250 


G 


gcvt function, 3-7, REF—252 
GENCAT command, 10-5 
getc function, REF—254 
getch function, REF—256 
getchar function, REF—-257 


getchar_ unlocked function, REF—258 


getclock function, REF—259 
getcwd function, REF—260 
getc_unlocked function, REF—255 
getdtablesize function, REF-261 
getegid function, REF-262 
getenv function, REF-—263 


using with putenv function, REF-—476 


geteuid function, REF-265 
getgid function, REF-266 
getgrent function, REF-—267 
getgrgid function, REF—-268 
getgrgid_r function, REF-269 
getgrnam function, REF-271 
getgrnam_r function, REF-272 
getgroup function, REF—274 
getitimer function, REF-275 
getlogin function, REF-277 


getname function, REF—278, REF—460 


getopt function, REF-—279 
getpagesize function, REF—282 
getpgid function, REF-283 
getpgrp function, REF—284 
getpid function, REF-285 
getppid function, REF—286 
getpwent function, REF—287 
getpwnam function, REF-—289 
getpwnam_r function, REF-289 
getpwuid function, REF—-292 
getpwuid_r function, REF-292 
gets function, REF-—194, REF-295 
getsid function, REF-296 
getstr function, REF-—297 
gettimeofday function, REF—-298 
getuid function, REF-299 

getw function, REF-300 

getwc function, REF-301 
getwchar function, REF—302 


getyx function, REF—303 
GIDs, 1-44 
glob function, REF-304 
globfree function, REF-308 
gmtime function, REF-309 
gmtime_r function, REF—309 
GNV 
symbolic link support, 12-17 
Group database functions 
endgrent, REF-152 
getgrent, REF—267 
getgrgid, REF-268 
getgrgid_ r, REF—269 
getgrnam, REF-271 
getgrnam_r, REF-272 
setgrent, REF—526 
Group Identifier, 1-44 
gsignal function, 4-5, 4-10, REF-311 
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Header files, 1-1, 1-15 
displaying on Alpha or I64 systems, 1-1 
displaying on VAX systems, 1-1 

hypot function, REF-313 


iconv function, 10-6, REF-314 
iconv_close function, 10-6, REF-316 
iconv_open function, 10-6, REF-317 
ilogb function, REF-319 
IMAGELIB.OLB, 1-3 
inch function, REF-320 
index function, REF-321 
initscr function, REF—322 
initstate function, REF-323 
using with setstate function, REF-543 
Input and output (I/O), 1-44 to 1-50 
conversion specifications, 2—7 to 2-19 
format specification string, 2—7, 2-13 
OpenVMS system services, 1-45 
record access 
in HPC, 1-48 
Record Management Services (RMS), 1-45 
Standard, 1-45 
stream access 
in HPC, 1-48 
UNIX, 1-45 
Wide-character, 2-6 
insch function, REF-325 
insertl1n function, REF-326 
insstr function, REF—327 
insstr macro, 6-2 
International software 
description of, 10-2 


Internationalization support, 10-1 
Interprocess communication, 5-1 
isalnum function, REF-328 
isalpha function, REF-329 
isapipe function, REF-—330 
isascii function, REF-331 
isatty function, REF-332 
iscntrl function, REF-333 
isdigit function, REF-334 
isgraph function, REF-335 
islower function, REF-336 
isgnan function, REF-337 
isprint function, REF-338 
ispunct function, REF-339 
isspace function, REF-340 
isupper function, REF-341 
iswalnum function, REF-342 
iswalpha function, REF—343 
iswentrl function, REF-344 
iswctype function, REF—345 
iswdigit function, REF—-347 
iswgraph function, REF—-348 
iswlower function, REF-349 
iswprint function, REF—350 
iswpunct function, REF-351 
iswspace function, REF-—352 
iswupper function, REF—353 
iswxdigit function, REF—354 
isxdigit function, REF—355 
itimerval structure, REF—275, REF-527 
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j0 function, REF-356 
j1 function, REF—-356 
jn function, REF-356 
jrand48 function, REF-357 


K 


kill function, REF—358 


L 


164a function, REF-359 

labs function, REF-360 

LANG logical name, 10-5 

Large files, 1-26 

_LARGEFILE macro, 1-26 

lchown function, REF-361 

lcong48 function, REF-362 
using with drand48 function, REF-—146 
using with lrand48 function, REF-380 
using with mrand48 function, REF—420 

LC_ALL category, 10-4 

LC_ALL logical name, 10-5 
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LC_CTYPE category, 10-9 
LC_NUMERIC logical name, 10-5 
ldexp function, REF-363 
ldiv function, REF-364 
leaveok function, REF—365 
lgamma function, REF-366 
LIB$ESTABLISH function, 4—11, REF—714 
LIB$SIGNAL, 4-10 
Libraries 
HP C RTL object-module linking order, 1-8 
Library 
main function, 1-2 
link function, REF-367 
Linker 
search libraries, 1-2 
Linking 
with RTL object libraries, 1-4 
Linking with the C RTL, 1-8 to 1-14 
List-handling functions 
va_arg, REF—716 
va_count macro, REF-—717 
va_end, REF-718 
va_start, REF-719 
va_start_1, REF-719 
llabs function, REF—483 
lldiv function, REF—484 
LNK$LIBRARY logical name, 1-3, 1-8 
Locale 
categories, 10-3 
description of, 10-3 
extracting information from, 10-8 
Locale support functions 
localeconv, REF-368 
nl_langinfo, REF—442 
setlocale, REF-—532 
localeconv function, 10-8, REF-368 
localtime function, REF-372 
using with tzset function, REF—694 
localtime_r function, REF-372 
log function, REF-374 
log10 function, REF-374 
logip function, REF-375 
logb function, REF-376 
Logical name 
for default locale, 10-5 
for default locale categories, 10-5 
for international environment, 10-5 
for locale directory, 10-4 
for system default locale, 10-5 
LANG, 10-5 
LC_ALL, 10-5 
LC_NUMERIC, 10-5 
SYS$I18N_LOCALE, 10-4 
SYS$LANG, 10-5 
SYS$LC_ALL, 10-5 
Logical names 
feature, 1-28 


Index-8 


long jmp function, 4-11, REF-377, REF-714, 
REF-721 
longjmp member 
using with ftw function, REF—243 
longname function, REF-379 
lrand48 function, REF-380 
using with 1cong48 function, REF-362 
using with seed48 function, REF-518 
using with srand48 function, REF—588 
lrint function, REF-381 
lround function, REF—382 
lseek function, 1-47, REF-383 
lstat function, REF—385 
lwait function, REF-386 


Macros 
feature-test, 1-18 
main function 
using with wait3 function, REF—741 
using with wait4 function, REF—744 
using with waitpid function, REF-747 
Main function, 1-2, 4-11 
main_program option, 1-2 
malloc function, 8-1, REF—56, REF-387 
using with ftw function, REF—243 
using with putenv function, REF-—476 
Math functions, 7-1 to 7-6 
abs, REF-6 
acos, REF-9 
acosh, REF—10 
asin, REF-16 
asinh, REF-17 
atan, REF-19 
atan2, REF-20 
atanh, REF-21 
cabs, REF-35 
cacos, REF-36 
cacosh, REF-37 
carg, REF-39 
casin, REF—40 
casinh, REF-41 
catan, REF—42 
catanh, REF-43 
cbrt, REF-51 
ccos, REF-52 
ccosh, REF-53 
ceil, REF-54 
cexp, REF-55 
cimag, REF-60 
clog, REF-—70 
con}, REF-79 
copysign, REF-80 
cos, REF-81 
cosh, REF-82 
cot, REF-83 
cpow, REF-84 


Math functions (cont’d) 


cproj, REF-85 
creal, REF-86 
csin, REF-95 
csinh, REF~-96 
csqrt, REF-97 


Math functions (cont'd) 
sqrt, REF-586 
srand, REF-587 
tan, REF-671 
tanh, REF-672 
tgamma, REF-676 


ctan, REF-98 trunc, REF-690 
ctanh, REF~-99 unordered, REF-—704 
div, REF-141 yO, REF-815 

erf, REF-157 yl, REF-815 

errno values, 7-1 yn, REF-815 

exp, REF-167 mblen function, REF-389 


exp2, REF-168 
fabs, REF—-169 
fdim, REF-181 
finite, REF-200 
floor, REF—202 
fma, REF—203 
fmax, REF-204 
fmin, REF~205 


mbrilen function, REF-390 

mbrtowc function, 3-7, 10-10, REF—391 

mbsinit function, REF-395 

mbsrtowcs function, 3-7, 10-10, REF-396 

mbstate t, 10-11, REF-390, REF-391, 
REF-—395, REF—396, REF—750, REF—774 

mbstowcs function, 10-10, REF—393 

mbtowc function, 3-7, 10-10, REF-394 


fp class, REF-—209 memccpy function, REF—398 
fp_classf, REF-209 memchr function, REF-399 
fp classl, REF-209 memcmp function, REF—400 


frexp, REF-223 
hypot, REF-313 
ilogb, REF-319 
isnan, REF-337 
30, REF-356 

jl, REF-356 

jn, REF-356 
labs, REF-360 
ldexp, REF-363 
ldiv, REF-364 
lgamma, REF-366 
llabs, REF—483 
lldiv, REF-484 
log, REF-374 
log10, REF-374 
loglp, REF-375 
logb, REF-376 
lrint, REF-381 
lround, REF-382 
modf, REF-416 


nextafter, REF—437 
nexttoward, REF-438 


nint, REF-440 
pow, REF—468 
gabs, REF-483 
qdiv, REF-484 
rand, REF—487 


remainder, REF-502 


remquo, REF—503 
rint, REF-510 
scalb, REF-513 


shm_ open, REF-547 
shm unlink, REF-—549 


sin, REF-579 
sinh, REF-580 


memcpy function, REF-—401 
memmove function, REF—402 
Memory allocation 
introduction to, 8-1 
program examples, 8-2 
Memory allocation functions 
brk, REF-30 
calloc, REF-38 
cfree, REF—56 
free, REF-221 
malloc, REF—-387 
realloc, REF—498 
sbrk, REF-512 
Memory reallocation, REF-221 
memset function, REF—403 
Message catalog, 10-3 
creating, 10-5 
Messaging functions 
catclose, REF—44 
catgets, REF-—45 
catopen, REF-48 
mkdir function, REF—404 
mkstemp function, REF-407 
mktemp function, REF-—408 
mktime function, REF—409 
using with tzset function, REF—694 
mmap function, REF—411 
modf function, REF—416 
Modules 
HP C RTL object linking order, 1-8 
Monetary formatting function 
strfmon, REF-614 
Monetary function, 10-9 
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Mount points, 12-2, 12-14 
move function, REF—417 
mprotect function, REF-—418 
mrand48 function, REF—420 
using with 1cong48 function, REF-362 
using with seed48 function, REF—-518 
using with srand48 function, REF—588 
msync function, REF-—421 
Multibyte character 
conversion to wide character, 10-10 
Multibyte character support 
btowc, REF-33 
mblen, REF-389 
mbrlen, REF-390 
mbrtowc, REF-391 
mbsinit, REF-395 
mbtowc, REF—-394 
wertomb, REF-—750 
wctob, REF—796 
wctomb, REF—797 
Multibyte string support 
mbsrtowcs, REF-396 
mbstowcs, REF-393 
wcesrtombs, REF-774 
wcstombs, REF—786 


MULTITHREAD reentrancy, 1-56, REF—124 


Multithread Restrictions, 1-58 
munmap function, REF-—423 
mvaddch function, REF—424 
mvaddstr function, REF—425 
mvcur function, REF—426 
mvdelch function, REF—427 
mvgetch function, REF—428 
mvgetstr function, REF-—429 
mvinch function, REF—430 
mvinsch function, REF—431 
mvinsstr function, REF—432 
mvinsstr macro, 6-2 
mvwaddch function, REF—424 
mvwaddstr function, REF-425 
mvwdelch function, REF—427 
mvwgetch function, REF—428 
mvwgetstr function, REF—429 
mvwin function, REF—433 
mvwinch function, REF—430 
mvwinsch function, REF—431 
mvwinsstr function, REF—432 
mvwinsstr macro, 6-2 


N 


nanosleep function, REF—434 
New features, xxix 

newwin function, REF—436 
nextafter function, REF—437 
nexttoward function, REF—438 
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NFS 

symbolic link support, 12-15 
nice function, REF-—439 
nint function, REF-—440 
nl function, REF—441 
nl_langinfo function, 10-8, REF—442 
nocrmode function, REF—93 
noecho function, REF-—148 
NONE reentrancy, REF—124 
nonl function, REF-—441 
Nonthread-safe functions, 1-57 
noraw function, REF—489 
nrand48 function, REF—446 


O 


Object libraries 
RTL, 1-4 

Object library 
VAXCRTL.OLB, 1-4 
VAXCRTLD.OLB, 1-4 
VAXCRTLDX.OLB, 1-4 
VAXCRTLT.OLB, 1-4 
VAXCRTLTX.OLB, 1-4 
VAXCRTLX.OLB, 1-4 

Object module 
HP C RTL linking order, 1-8 

Occlusion, 6—4 

ODS-5 volumes, 1-18 


open function, REF-147, REF-173, REF-182, 


REF—447 

opendir function, REF—450 

using with readdir function, REF—493 

using with rewinddir function, REF-—508 
OpenVMS system services 

in HPC programs, 1-45 
OpenVMS versions, A-1 
Operating system version dependency, A-1 
overlay function, REF—-29, REF—452 
overwrite function, REF—-29, REF—453 


P 


passwd structure, REF—287, REF—290, REF—293 


Password encryption functions 
crypt, REF-94 
encrypt, REF-151 
setkey, REF-531 
pathconf function, REF—454 
pause function, REF—456 
pclose function, REF—457 
using with popen function, REF—466 
perror function, 4-5, REF—458 


pipe function, REF-147, REF-173, REF-182, 


REF—459 
Pointers 
64-bit support, 1-58 


poll function, REF-463 
popen function, REF—466 
Portability concerns, 1-45 
arguments to mkdir, REF-—404 
_exit function, REF-165 
gsignal function, REF-311 
longname function, REF-379 
memory deallocation, REF-—56 
mvcur function, 6—10 
mv [w] insstr functions, REF—432 
[no]nl functions, REF-441 
POSIX pathnames, 12-1 
radix conversion specifiers, 2-11 
raise function, REF-—486 
specific 
list of, 1-53 to 1-55 
ssignal function, REF-592 
Symbolic links, 12-1 
ttyname function, REF-692 
ttyname_r function, REF-692 
UNIX file specifications, 1-15 
ambiguity of, 1-16 
variable-length argument lists, 3-9 
va_start_1 macro, REF—719 
vfork versus fork function, REF—721 
[w] clrattr functions, REF—74 
[w] insstr functions, REF-327 
[w] setattr functions, REF—520 
POSIX pathnames, 1-18, 12—1 to 12-18 
POSIX root, 12-2 
POSIX Root Support, 1-32 
POSIX style identifiers, 1-44 
POSIX threads library, 1-56 
_POSIX_C_SOURCE macro, 1-19 
_POSIX_EXIT macro, 1-24, 1-25, 1-27 
pow function, REF—468 
pread function, REF—469 
Predefined macro 
ERR, 6-10 
Predefined variables and constants, 6—9 
printf function, REF-470 
printw function, REF-471 
Process permanent files, 2-19 
putc function, REF-—472 
putchar function, REF—474 
putchar_ unlocked function, REF—475 
putc_unlocked function, REF—473 
putenv function, REF—476 
puts function, REF—478 
putw function, REF—479 
putwc function, REF-—480 
putwchar function, REF—481 
pwrite function, REF—482 


Q 


qabs function, REF—483 
qdiv function, REF—484 
qsort function, REF—485 
Quotas 

affecting RTL, 5-1, 5-2, 5-5 


R 


raise function, 4—5, 4-10, REF—358, REF—486 
rand function, REF—487 
random function, REF-—488 
raw function, REF—489 
read function, REF-491 
readdir function, REF—493 
using with closedir function, REF—72 
readdir r function, REF—493 
readlink function, REF—495 
readv function, REF—496 
realloc function, 8—1, REF-498 
realpath function, REF—500 
Record 
access by HPC, 1-48 
VO 
HP C handling of, 1-49 
Record files 
accessing in record mode, 1-48 
accessing in stream mode, 1-48 
Record Management Services (RMS) 
accessing files, 1-48 
file organization, 1-46 
in HPC programs, 1-45 
overview of, 1-46 to 1-50 
record access 
in HPC, 1-48 
record formats, 1-47 
stream access 
in HPC, 1-48 
Reentrancy, 1-55, REF—-124 
AST, 1-55, REF-124 
MULTITHREAD, 1-56, REF-124 
NONE, REF-124 
Restrictions, 1-58 
TOLERANT, 1-56, REF—124 
Reentrancy function 
deccSset_reentrancy, 1-56, REF-124 
/REENTRANCY qualifier, 1-56 
refresh function, REF-64, REF-501 
remainder function, REF-502, REF—503 
remove function, REF—135, REF-504 
remquo function, REF—502, REF—503 
rename function, REF-—505 
Reserved POSIX filenames, 12-3 
rewind function, REF-—507 
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rewinddir function 
using with readdir function, REF-—493 
rindex function, REF-—509 
rint function, REF-510 
rmdir function, REF-511 
RMS 
file attributes, 2-4 
Root, POSIX, 12-2 
Run-Time Library (RTL) 
as shared images, 1-2 
Curses functions and macros, 6-1 
Date/time functions, 11-1 
header files, 1-15 
I/O, 1-44 to 1-50 
HP C handling of, 1-48 to 1-50 
interpreting syntax, 1-14 
introduction to, 1—1 to 1-68 


linking against RTL object libraries, 1-4, 1-8 


linking against RTL shareable image, 1-3 
linking options explained, 1-3 to 1-14 
portability concerns, 1-45 

preprocessor directives, 1-15 

specific portability concerns, 1-53 to 1-55 
stream I/O, 1-48 


S 


sbrk function, 8-1, REF—-512 
scalb function, REF-513 
scanf function, REF-514 
scanw function, REF—515 
Screen management 


Curses 
See Curses 
scroll function, REF-516 
scrollok function, REF-517 
Security/impersonation functions 
getegid, REF-262 
geteuid, REF-265 
getgid, REF-266 
getgroup, REF-274 
getpgid, REF-283 
getpgrp, REF-284 
getsid, REF-296 
getuid, REF-299 
seteuid, REF-524 
setgid, REF-525 
setpgid, REF-536 
setpgrp, REF-538 
setregid, REF—-540 
setreuid, REF-541 
setsid, REF-542 
setuid, REF-544 
seed48 function, REF-518 
using with drand48 function, REF—146 
using with 1cong48 function, REF-362 
using with lrand48 function, REF-380 
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seed48 function (cont’d) 

using with mrand48 function, REF—420 
seekdir function, REF-519 
setattr function, REF—520 
setattr macro, 6-2 
setbuf function, REF-521 
setenv function, REF—522 
seteuid function, REF-524 
setgid function, REF-525 
setgrent function, REF-526 
setitimer function, REF—527 

using with ualarm function, REF-698 
set jmp function, 4-11, REF-377, REF-529, 

REF-714, REF—721 

setkey function, REF-531 
setlocale function, 10-4, REF-532 
setpgid function, REF—-536 
setpgrp function, REF-538 
setpwent function, REF-539 
setregid function, REF-540 
setreuid function, REF-541 
setsid function, REF-542 
setstate function, REF-543 

using with initstate function, REF-323 
setuid function, REF-544 
setvbuf function, REF-545 

using with popen function, REF—466 
Shareable image, 1-3 
Shared image 

HPCRTL, 1-2 
shm_open function, REF-547 
shm_ unlink function, REF-549 
sigaction function, REF-550 
sigaction structure, REF-550 
sigaddset function, REF—-553 
sigblock function, 4-7, REF-554, REF-564 
sigdelset function, REF—-555 
sigemptyset function, REF—556 
sigfillset function, REF-557 
sighold function, REF-558 
sigignore function, REF—559 
sigismember function, REF—560 
siglongjmp function, REF-561 
sigmask function, REF—-562 


signal function, 4~7, 4-11, REF-311, REF—486, 


REF-—563, REF—592 

Signal handler 

calling interface, 4-7 
Signal-handling functions, 4-5 

alarm, REF-13 

gsignal, REF-311 

kill, REF-358 

longjmp, REF-377 

OpenVMS exceptions, 4-10 

pause, REF-—456 

program examples, 4-14 

raise, REF-—486 

setjmp, REF-529 


Signal-handling functions (cont'd) 
sigaction, REF-—550 
sigaddset, REF-553 
sigblock, REF-554 
sigdelset, REF-555 
sigemptyset, REF—556 
sigfillset, REF—557 
sighold, REF-558 
sigignore, REF-—559 
sigismember, REF—560 
siglongjmp, REF-561 
sigmask, REF—-562 
signal, REF-563 
sigpause, REF—564 
sigpending, REF-—565 
sigprocmask, REF—566 
sigrelse, REF-568 
sigsetjmp, REF-569 
sigsetmask, REF-571 
sigstack, REF-572 
sigsuspend, REF-574 
sigtimedwait, REF-575 
sigvec, REF-576 
sigwait, REF-577 
sigwaitinfo, REF—-578 
sleep, REF-581 
ssignal, REF-592 
UNIX signals, 4-6 
VAXCSESTABLISH, REF-714 

<Signal.h> header file, 4-6 

Signals, 4-5 

sigpause function, REF—564 

sigpending function, REF-565 

sigprocmask function, REF—566 

sigrelse function, REF—568 

sigsetjmp function, REF-569 

sigsetmask function, 4-7, REF-571 

sigstack function, REF-572 

sigsuspend function, REF—574 

sigtimedwait function, REF—575 

sigvec function, 4~-7, 4-11, REF-311, REF—486, 

REF-576 

sigwait function, REF-577 

sigwaitinfo function, REF—578 

sin function, REF-579 

sinh function, REF—580 

sleep function, REF-581 

snprintf function, REF—582 

_SOCKADDR_LEN macro, 1—25 

socket routines 
documentation, xxv 
help, xxv 

Special files, 12-3 

Specification delimiters 
OpenVMS and UNIX, 1-16 

sprintf function, REF-584 


sqrt function, REF-586 
srand function, REF—587 
srand48 function, REF—588 
using with drand48 function, REF-—146 
using with 1cong48 function, REF-362 
using with lrand48 function, REF-—380 
using with mrand48 function, REF—420 
srandom function, REF—589 
using with random function, REF—488 
sscanf function, REF—590 
ssignal function, 4-7, REF-311, REF—486, 
REF-592 
Standard header file, 1-1 
Standard I/O, 1-45 
file pointers, 2-5 
introduction to, 2-1 
program example, 2-22 
wide character, 2-23 
Standard I/O functions 
clearerr, REF-62 
clearerr unlocked, REF-63 
delete, REF-135, REF—504 
dlclose, REF-142 
dlerror, REF-143 
dlopen, REF-144 
dlsym, REF-145 
fclose, REF-172 
fdopen, REF-182 
feof, REF—-183 
feof unlocked, REF-184 
ferror, REF—185 
ferror unlocked, REF-186 
fflush, REF-187 
fgetc, REF-189 
fgetc_ unlocked, REF-190 
fgetname, REF-191 
fgets, REF-194 
fgetwc, REF-196 
fgetws, REF-197 
flockfile, REF-201 
fopen, REF-207 
fprintf, REF-212 
fputc, REF-214 
fputc_unlocked, REF-215 
fputs, REF-216 
fputwc, REF-217 
fputws, REF-219 
fread, REF—220 
freopen, REF—222 
fscanf, REF—225 
fseek, REF-—227 
fseeko, REF—229 
ftell, REF-—237 
ftello, REF—238 
ftrylockfile, REF-241 
funlockfile, REF-—244 
fwrite, REF-249 
getc, REF-254 
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Standard I/O functions (cont’d) 
getchar unlocked, REF-258 
getc_unlocked, REF-255 
getw, REF-300 
getwc, REF-301 
mktemp, REF-408 
putc, REF-472 
putchar_ unlocked, REF-—475 
putc_unlocked, REF—473 
putw, REF-479 
putwc, REF-480 
rewind, REF-507 
setbuf, REF-521 
setvbuf, REF—545 
snprintf, REF—582 
sprintf, REF-584 
sscanf, REF-590 
tmpfile, REF-679 
tmpnam, REF-680 
ungetc, REF-701 
ungetwc, REF-702 

Standards 
listed, 1-19 

standend function, REF-—593 

standout function, REF—-594 

stat function, REF—-595 
using with ftw function, REF—242 

stat structure 
using with ftw function, REF—242 

statvfs function, REF-—600 

__STDC_VERSION__ macro, 1-19 

stderr, 2-20, REF—187, REF—222, REF-458, 

REF-461 

stdin, 2-20, REF-222, REF-461, REF-514 

<stdio.h> header file, 2-20 

stdout, 2-20, REF—222, REF—-461, REF—470, 

REF-474, REF-478, REF—481 

stdscr window, 6-5 

strcasecmp function, REF-602 

strcat function, REF-603 

strchr function, REF-399, REF-605 

strcmp function, REF—400, REF—-607 

strcmpn function, 1-54 

strcoll function, 10-11, REF—608 

strcpy function, REF—401, REF-609 

strcpyn function, 1-54 

strcspn function, REF-610 

strdup function, REF-611 

Stream 
access by HPC, 1-48 
files, 2-1 

strerror function, 4-5, REF-612 

strfmon function, 10-9, REF—614 

strftime function, 10-8, REF-618 
using with tzset function, REF—694 

String comparison functions 
multipass collation, 10-11 
wescoll, REF—756 
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String encoding functions 
crypt, REF-94 
encrypt, REF-151 
setkey, REF-531 

String-handling functions, 3-9 to 3-10 
atof, REF—-23 
atoi, REF-24 
atol, REF—24 
atoll, REF-25 
atog, REF-—25 
basename, REF—26 
bemp, REF-27 
bcopy, REF-28 
bzero, REF-34 
dirname, REF-139 
ffs, REF—-188 
index, REF-321 
memchr, REF-399 
memcmp, REF—400 
memcpy, REF-401 
memmove, REF-—402 
memset, REF—403 
program examples, 3-10 
rindex, REF-509 
strcasecmp, REF-602 
streat, REF-603 
strchr, REF-605 
strcmp, REF-607 
strcoll, REF—608 
strcpy, REF-609 
strcspn, REF-610 
strdup, REF-611 
strlen, REF-624 
strncasecmp, REF-625 
strncat, REF-626 
strncmp, REF-627 
strncpy, REF-629 
strnlen, REF-630 
strpbrk, REF-631 
strrchr, REF-637 
strsep, REF-638 
strspn, REF-639 
strtok, REF-644 
strtok_r, REF-644 
strtol, REF-647 
strtoll, REF-649 
strtog, REF-649 
strtoul, REF-651 
strtoull, REF-652 
strtoug, REF-652 
strxfrm, REF—-653 
swab, REF-657 
wescat, REF—-751 
weschr, REF—753 
wescmp, REF-755 
wescoll, REF-—756 
wescpy, REF—757 
wescspn, REF-758 


String-handling functions (cont’d) 
weslen, REF-—766 
wesncat, REF—767 
wcesncmp, REF—769 
wesncpy, REF-—770 
wespbrk, REF-771 
wesrchr, REF—772 
wesspn, REF-776 
westok, REF-781 
westol, REF—784 
westoul, REF—787 
weswcs, REF—790 
wesxfrm, REF—793 
strlen function, REF-624 
strncasecmp function, REF-625 
strncat function, REF—626 
strncmp function, REF-627 
strncpy function, REF-629 
strnlen function, REF-630 
strpbrk function, REF-631 
strptime function, 10-8, REF-632 
strrchr function, REF-—-637 
strsep function, REF-638 
strspn function, REF-639 
strstr function, REF-640 
strtod function, 10-9, REF—23, REF—642 
strtok function, REF-644 
strtok_r function, REF-644 
strtol function, REF—24, REF—25, REF-647 
strtoll function, REF-649 
strtoq function, REF-649 
strtoul function, REF-651 
strtoull function, REF-652 
strtoug function, REF-652 
strxfrm function, 10-11, REF—653 
Subprocess, 5-1 to 5-11 
executing image 
with exec functions, 5-3 
implementation of, 5-2 
introduction to, 5-1 
program examples, 5-5 to 5-11 
sharing data with pipe, 5-5, REF—459 
synchronization with wait, 5-5 
Subprocess functions 
decc$set_ child default dir, REF-119 
deccSset_child_standard_streams, 
REF-120 
decc$validate_wchar, REF—130 
decc$write eof to mbx, REF-131 
execl, REF-158 
execle, REF—-160 
execlp, REF-161 
execv, REF-162 
execve, REF-163 
execvp, REF-164 
pipe, REF—459 
vfork, REF-721 
wait, REF-739 


subwin function, REF—656 
swab function, REF—657 
swprintf function, REF—-658 
swscanf function, REF-—659 
Symbolic link functions 


lchown, REF-361 
lstat, REF-385 
readlink, REF—495 
realpath, REF-500 
symlink, REF-660 
unlink, REF—703 


Symbolic links, 1-18, 12-1 to 12-18 
symlink function, REF—660 
Synchronizing processes, 5-5 
Syntax 
of HP C RTL functions, 1-14 
SYS$ERROR, 2-20 
SYS$I18N_LOCALE logical name, 10-4 
SYS$INPUT, 2-20 
SYS$LANG logical name, 10-5 
SYS$LC_ALL logical name, 10-5 
SYS$OUTPUT, 2-20 
SYS$POSIX_ROOT, 1-382 
SYS$WAKE, REF-13 
sysconf function, REF—662 
system function, REF-669 
System functions, 9-1 to 9-5 


asctime, REF-14 


asctime r, REF-14 


assert, REF-18 
atexit, REF-22 
bsearch, REF-31 
chdir, REF-57 
chmod, REF-58 
chown, REF-59 
clock, REF-65 
ctermid, REF-—100 
ctime, REF-101 
ctime_r, REF-101 
cuserid, REF-—103 


difftime, REF-138 


fchmod, REF-—170 
fchown, REF-171 
fmod, REF-206 

ftime, REF—239 

getcwd, REF-260 
getenv, REF-263 
getpid, REF-285 
getppid, REF—-286 
gmtime, REF-309 


gmtime_ r, REF-309 


introduction to, 9-3 


localtime, REF-372 
localtime_r, REF-372 


memset, REF—403 
mkdir, REF-404 
nice, REF-—439 


program examples, 9-3 
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System functions (cont'd) Time-related functions (cont’d) 


gsort, REF—485 ctime, REF-101 
remainder, REF—502 ctime_r, REF-101 
remove, REF—-135, REF—504 decc$fix_ time, REF-113 
remquo, REF-503 difftime, REF-138 
rename, REF-505 ftime, REF-239 
setbuf, REF-521 getclock, REF-259 
setvbuf, REF-545 getitimer, REF-275 
strtod, REF-642 gettimeofday, REF-298 
strtok, REF-644 gmtime, REF—-309 
strtok_r, REF-644 gmtime r, REF-309 
system, REF-669 localtime_r, REF-372 
time, REF-677 mktime, REF-—409 
times, REF-678 nanosleep, REF—434 
umask, REF-699 setitimer, REF-527 
utime, REF—707 strftime, REF-618 
utimes, REF—710 strptime, REF-632 
vfprintf, REF—-723 time, REF-677 
vfscanf, REF-724 times, REF-678 
vprintf, REF-729 tzset, REF-694 
vscanf, REF—730 ualarm, REF-698 
vsnprintf, REF-731 usleep, REF—706 
vsprintf, REF-732 utime, REF—707 
vsscanf, REF-733 utimes, REF-710 
wcestod, REF—779 wcesftime, REF—760 
wcestok, REF-781 Time-zone cache, REF—697 
writev, REF-812 times function, REF-678 
timespec structure, REF-—259 
T tmpfile function, REF-679 
tmpnam function, REF-—680 
tan function, REF-671 toascii function, 3-7, REF-681 
tanh function, REF-672 TOLERANT reentrancy, 1-56, REF—-124 
telldir function, REF-673 tolower macro, 3-7 
tempnam function, REF—674 _tolower function, REF-683 
Terminal I/O tolower function, 3-7, REF—682 
program examples, 2-20 to 2-25 touchwin function, REF-684 
Terminal I/O functions _toupper macro, 3-7 
getchar, REF—-257 _toupper function, REF-686 
gets, REF-295 toupper function, 3-7, REF-685 
getwchar, REF-302 towctrans function, 3-7, 10-9, REF-687 
printf, REF-470 towlower function, 10-10, REF-688 
putchar, REF-474 towupper function, 10-10, REF—689 
puts, REF-478 trunc function, REF-690 
putwchar, REF-481 truncate function, REF-691 
scanf, REF—-514 ttyname function, REF-692 
tgamma function, REF-676 ttyname_r function, REF-692 
Thread-safety, 1-57 tzset function, REF-694 
Time 
introduction to, 11-1 U 
time function, REF-677 
Time functions, 11-1 to 11-6 ualarm function, REF-698 
Time-related functions UIDs, 1-44 
asctime, REF-14 umask function, REF-699 
asctime r, REF-14 umask value, 5-4 
clock, REF-65 uname function, REF—700 
clock getres, REF-66 ungetc function, REF—701 


clock gettime, REF-67 
clock settime, REF-68 
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ungetwc function, REF-—702 
UNIX 
file specification conversion functions, 1-16 
file specifications, 1-15 to 1-18 
alternate translation, 1-17 
compared to OpenVMS, 1-16 
Run-Time Library, 1-15 
use with HP C RTL, 1-15 to 1-18 
UNIX I/O, 1-45 
file descriptors, 2-5 
functions 
program example, 2-24 
UNIX I/O functions 
close, REF-71 
creat, REF—-87 
dup, REF-147 
dup2, REF-147 
fentl, REF-173 
fileno, REF-199 
fstat, REF-231 
getname, REF-278 
getopt, REF-279 
isapipe, REF-330 
isatty, REF-332 
lseek, REF-383 
open, REF-—447 
pread, REF—469 
pwrite, REF—-482 
read, REF-491 
readv, REF—496 
stat, REF—595 
ttyname, REF-692 
ttyname_r, REF-692 
write, REF-811 
UNIX style root, 1-32 
__UNIX_PUTC macro, 1-27 
unlink function, REF—703 
unordered function, REF—704 
unsetenv function, REF—705 
User database functions 
endpwent, REF-153 
getpwuid, REF-292 
getpwuid_r, REF-292 
setpwent, REF—539 
User Identifier, 1-44 
_USE_STD_STAT macro, 1-26 
usleep function, REF—706 
utime function, REF—707 
utimes function, REF—710 
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<varargs.h> header file, 3-9 

Variable-length argument lists, 3-9 

Variable-length record files 
accessing in record mode, 1-51 


VAXCSCRTL_INIT function, 4-11, REF-699, 
REF-713 

vaxcSerrno external variable, 4—5 

VAXCSESTABLISH function, 4—11, REF-377, 
REF-529, REF-714 

VAXC$EXECMBX logical name, 5—4 

va_arg function, REF-716 

va_count macro, REF-—717 

va_end function, REF-—718 

va_start macro, REF-—719 

va_start_1 macro, REF-—719 

Version-dependency of HP C RTL routines, A-1 

vfork function, REF—460, REF-721 

vfprintf function, REF—723 

vfscanf function, REF—724 

vfwprintf function, REF—726 

vfwscanf function, REF—728 

_VMS_CURSES macro, 1-25 

_VMS_V6_SOURCE macro, 1-24 

__VMS_VER macro, 1-23 

__VMS_VER_OVERRIDE macro, 1-24 

vprintf function, REF—729 

vscanf function, REF—730 

vsnprintf function, REF-731 

vsprintf function, REF—732 

vsscanf function, REF—733 

vswprintf function, REF—734 

vswscanf function, REF—736 

vwprintf function, REF—737 

vwscanf function, REF—738 
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waddch function, REF-11 
waddstr function, REF—12 
wait function, REF—739 

using with waitpid function, REF—746 
wait3 function, REF—740 
wait4 function, REF—743 
waitpid function, REF—746 
wclear function, REF-61 
wclrattr function, 6-2, REF—74 
wclrtobot function, REF—75 
wclrtoeol function, REF—76 
wcertomb function, 3-7, 10-10, REF—750 
wescat function, REF-751 
weschr function, REF—753 
wcscmp function, REF—755 
wcscoll function, 10-11, REF—756 
wcscpy function, REF—757 
wcscspn function, REF-—758 
wcsftime function, 10-8, REF—760 
weslen function, REF—766 
wesncat function, REF—767 
wcsncmp function, REF—769 
wcsncpy function, REF—770 
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wcspbrk function, REF-771 
wesrchr function, REF—772 


wcsrtombs function, 3-7, 10-10, REF—774 


wcsspn function, REF-—776 
wesstr function, REF—778 


wcstod function, 10-9, REF—779 


wcstok function, REF-—781 
wcstol function, REF—784 


wcstombs function, 10-10, REF—786 


wcstoul function, REF-—787 
wcswcs function, REF—790 
wcswidth function, REF—792 


wcesxfrm function, 10-11, REF—793 
wctob function, 10-10, REF—796 
wctomb function, 10-10, REF—797 
wctrans function, 3-7, 10-9, REF—798 


wctype function, REF—799 
wcwidth function, REF-802 
wdelch function, REF-—134 
wdeleteln function, REF—136 
werase function, REF—156 


wgetch function, REF—-148, REF—256 
wgetstr function, REF—-148, REF—297 


Wide character 
collating functions, 10-11 


conversion to multibyte, 10-10 


data type, 10-9 
functions, 10-9 
I/O functions, 10-10 
Wide character I/O 
program example, 2-23 
Wide-character functions 
btowc, REF-33 
fgetwc, REF-196 
fgetws, REF-197 
fputwc, REF-217 
fputws, REF-219 
fwide, REF—246 
fwprintf, REF-247 
fwscanf, REF—250 
getwc, REF-301 
getwchar, REF-302 
iswalnum, REF-342 
iswalpha, REF-343 
iswentrl, REF~-344 
iswctype, REF-345 
iswdigit, REF—-347 
iswgraph, REF-348 
iswlower, REF-349 
iswprint, REF—-350 
iswpunct, REF-351 
iswspace, REF-352 
iswupper, REF-353 
iswxdigit, REF-354 
mbrlen, REF-390 
mbrtowc, REF-391 
mbsinit, REF-395 
mbsrtowcs, REF-396 
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Wide-character functions (cont'd) 
putwc, REF-—480 
putwchar, REF-481 
swprintf, REF-658 
swscanf, REF-659 
towctrans, REF-687 
towlower, REF-688 
towupper, REF-689 
ungetwc, REF-702 
vfwprintf, REF—726 
vfwscanf, REF—728 
vswprintf, REF-734 
vswscanf, REF—736 
vwprintf, REF—-737 
vwscanf, REF—738 
wertomb, REF—750 
wescat, REF—-751 
weschr, REF—753 
wescmp, REF—755 
wescoll, REF-—756 
wescpy, REF-757 
wescspn, REF-758 
wesftime, REF—760 
wcslen, REF—766 
wesncat, REF-767 
wesncemp, REF-—769 
wesncpy, REF-—770 
wespbrk, REF-771 
wesrchr, REF-772 
wcesrtombs, REF-774 
wcesspn, REF-776 
wesstr, REF—-778 
wcestod, REF-779 
wcestok, REF—781 
westol, REF-784 
westoul, REF-—787 
wcswcs, REF—790 
wceswidth, REF—792 
wcesxfrm, REF—793 
wctob, REF—796 
wctrans, REF-798 
wctype, REF-799 
wewidth, REF-802 
wmemchr, REF-803 
wmemcmp, REF-804 
wmemcpy, REF-805 
wmemmove, REF-806 
wmemset, REF—807 
wprintf, REF-808 
wscanf, REF-814 

Wide-character I/O, 2-6 

winch function, REF-320 

winsch function, REF-—325 
winsertln function, REF-326 
winsstr function, 6-2, REF—327 
wmemchr function, REF—803 


wmemcmp function, REF-—804 
wmemcpy function, REF-—805 
wmemmove function, REF—806 
wmemset function, REF—807 
wmove function, REF—417 
wprintf function, REF—808 
wprintw function, REF—471 
wrapok function, REF-810 
wrefresh function, REF-501 
write function, REF-811 
writev function, REF-812 
wscanf function, REF—814 
wscanw function, REF—-515 


wsetattr function, 6-2, REF—520 


wstandend function, REF—593 
wstandout function, REF—594 


X 


_XOPEN_SOURCE macro, 1-19 


_XOPEN_SOURCE_EXTENDED macro, 1-19 


Y 


yO function, REF-815 
yl function, REF-815 
yn function, REF-815 
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